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Secure sockets APIs 


Secure sockets consists of the following APIs: 
e OS/400 Global Secure Toolkit (GSKit) APIs 


e OS/400 SSL_ APIs 


The OS/400 Global Secure Toolkit (GSKit) and OS/400 SSL_ application programming interfaces (APIs) 
are a set of functions that, when used with the OS/400 sockets APIs, are designed to enable and facilitate 
secure communications between processes on a network. The GSK Secure Toolkit (GSKit) APIs are the 
preferred set of APIs to be used to securely enable an application using Secure Sockets Layer/Transport 
Layer Security (SSL/TLS). The SSL_ APIs also can be used to enable an application to use the SSL/TLS 
Protocol. 


SSL provides communications privacy over an open communications network (that is, the Internet). The 
protocol allows client/server applications to communicate to prevent eavesdropping, tampering, and 
message forgery. The SSL protocol connection security has three basic properties: 


e The connection is private. Encryption using secret keys is used to encrypt and decrypt the data. The 
secret keys are generated on a per SSL session basis using an SSL handshake protocol. An SSL 
handshake is a series of protocol packets sent in a particular sequence, which use asymmetric 
cryptography to establish an SSL session. Symmetric cryptography is used for application data 
encryption and decryption. 


e The peer's identity can be authenticated using asymmetric, or public key cryptography. 


e The connection is reliable. Message transport includes a message integrity check using a keyed 
Message Authentication Code (MAC). Secure hash functions are used for MAC computations. 


When creating ILE programs or service programs that use the OS/400 GSKit or SSL_ APIs, you do not 
need to explicitly bind to the secure sockets service program QS YS/QSOSSLSR because it is part of the 
system binding directory. 


The GSKit and SSL_ API documentation describes the GSKit and SSL_ APIs only. This documentation 
does not include any information about how to configure or obtain any of the cryptographic objects, such as 
a key ring file or certificate, that are required to fully enable an application for SSL. Some cryptographic 
objects, such as certificate store files, are required parameters for GSKit and SSL_ APIs. Information on 
how to configure the cryptographic objects required for the OS/400 secure socket APIs, or how to configure 
a secure web server, which also uses the secure socket APIs, can be found using the following references: 


e HTTP Server: Documentationta 


e Secure Sockets Layer (SSL) under the Security topic. Plan for enabling SSL discusses what you 
must install and configure before using secure sockets. 


e Cryptographic Hardware topic. 


For background information on GSKit and SSL_ APIs, see: 


e Secure Sockets in the Sockets programming topic. 
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OS/400 Global Secure Toolkit (GSKit) APIs 


OS/400 GSkit APIs, when used in addition to the existing OS/400 Sockets APIs, provide the functions 
required for applications to establish secure communications. An application using GSKit for secure 
communications basically is a client/server application written using sockets. 


The Global Secure Toolkit (GSKit) APIs are: 


gsk_attribute_get_bufferQ (Get character information about a secure session or an SSL 
environment) is used to obtain specific character string information about a secure session or an 
SSL environment. 

gsk_attribute_get_cert_info() (Get information about a local or partner certificate) is used to obtain 


specific information about either the server or client certificate for a secure session or an SSL 
environment. 


gsk_attribute_get_enum( (Get enumerated information for a secure session or an SSL 


environment) is used to obtain values for specific enumerated data for a secure session or an SSL 
environment. 


gsk_attribute_get_numeric_value() (Get numeric information about a secure session or an SSL 


environment) is used to obtain specific numeric information about a secure session or an SSL 
environment. 


gsk_attribute_set_bufferQ (Set character information for a secure session or an SSL environment) 


is used to set a specified buffer attribute to a value inside the specified secure session or SSL 
environment. 


gsk_attribute_set_enumQ (Set enumerated information for a secure session or an SSL environment) 
is used to set a specified enumerated type attribute to an enumerated value in the secure session or 
SSL environment. 

gsk_attribute_set_numeric_value(Q (Set numeric information for a secure session or an SSL 


environment) is used to set specific numeric information for a secure session or an SSL 
environment. 


gsk_environment_close() (Close an SSL environment) is used to close the SSL environment and 
release all storage associated with the environment. 


gsk_environment_init() (Initialize an SSL environment) is used to initialize the SSL environment 
after any required attributes are set. 


gsk_environment_open() (Get a handle for an SSL environment) is used to get storage for the SSL 
environment. 


gsk_secure_soc_close(Q) (Close a secure session) is used to close a secure session and free all the 
associated resources for that secure session. 


gsk_secure_soc_initQ) (Negotiate a secure session) is used to negotiate a secure session, using the 
attributes set for the SSL environment and the secure session. 


gsk_secure_soc_misc() (Perform miscellaneous functions for a secure session) is used to perform 
miscellaneous functions for a secure session. 


gsk_secure_soc_open() (Get a handle for a secure session) is used to get storage for a secure 


session, set default values for attributes, and return a handle that must be saved and used on secure 
session-related function calls. 


gsk_secure_soc_read() (Receive data on a secure session) is used by a program to receive data from 
a secure session. 


#esk_secure_soc_startInit() (Start asynchronous operation to negotiate a secure session) initiates 


an asynchronous negotiation of a secure session, using the attributes set for the SSL environment 
and the secure session.*& 

e@ gsk secure_soc_startRecv() (Start asynchronous receive operation on a secure session) is used to 
initiate an asynchronous receive operation on a secure session. 


e@ gsk secure_soc_startSendQ( (Start asynchronous send operation on a secure session) is used to 
initiate an asynchronous send operation on a secure session. 


e gsk secure_soc_write() (Send data on a secure session) is used by a program to write data on a 
secure session. 


e gsk strerror() (Retrieve GSKit runtime error message) is used to retrieve an error message and 
associated text string that describes a return value that was returned from calling a GSKit API. 


Note: These functions use header (include) files from the library QS YSINC, which is optionally installable. 
Make sure QSYSINC is installed on your system before using any of the functions. See Header Files for 


UNIX-Type Functions for the file and member name of each header file. 


See the following examples in the Socket programming topic for more information: 


e Example: GSKit secure server with asynchronous data receive 


e Example: GSKit secure server with asynchronous handshake 


e Example: Establish a secure client with GSKit APIs 
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gsk_attribute_get_buffer()--Get character 
information about a secure session or an SSL 
environment 


Syntax 


#include <gskssl.h> 


int gsk_attribute_get_buffer(gsk_handle my_gsk_handle, 
GSK_BUF_ID bufID, 
const char **buffer, 
int *bufSize); 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_attribute_get_buffer() function is used to obtain specific character string information about a 
secure session or an SSL environment. It can be used to obtain values such as certificate store file, 
certificate store password, application ID, and ciphers. 


Parameters 


my_gsk_handle (Input) 
Indicates one of the following handles: 
o The handle for the secure session (my_session_handle) 


o The handle for the SSL environment (my_env_handle) 


bufID (Input) 


The following values can be used to retrieve information about the secure session or the SSL 
environment that is either defaulted or explicitly set: 


o GSK_KEYRING_FILE (201) - buffer points to the name of the certificate store file being 
used for the SSL environment. 


o GSK_KEYRING_PW (202) - buffer points to the password for the certificate store file 
being used for the SSL environment. 


o GSK_KEYRING_LABEL (203) - buffer points to the certificate label associated with the 
certificate in the certificate store identified by GSK_KEYRING_FILE to be used for the 
secure session or SSL environment. 


o GSK_OS400_APPLICATION_ID (6999) - buffer points to the application identifier 
being used for the SSL environment. 


o GSK_V2_CIPHER_SPECS (205) - buffer points to the list of available SSL Version 2 
ciphers to be used for the secure session or the SSL environment. See the usage notes in 
gsk_attribute_set_buffer() API for the format of the ciphers. 


o GSK_V3_CIPHER_SPECS (206) - buffer points to the list of available SSL Version 3 or 
TLS Version 1 ciphers to be used for the secure session or the SSL environment. See the 
usage notes in gsk_attribute_set_buffer() API for the format of the ciphers. 


o GSK_CONNECT_SEC_TYPE (208) - buffer points to a string containing "SSLV2," 
"SSLV3," or "TLSV1," depending on what was actually negotiated for use by the secure 
session. 


o GSK_CONNECT_CIPHER_SPEC (207) - buffer points to a one- or two-character string 
describing the cipher specification negotiated for use by the secure session. See the usage 
notes in gsk_attribute_set_buffer() API for the format of the ciphers. 


buffer (Output) 


The address of the location to place the pointer that will point to the buffer containing the requested 
information. The storage for this information was allocated by the system from user heap storage 
and will be freed by the gsk_secure_soc_close() API or the gsk_environment_close() API. 


The data in the buffer is assumed to be represented in the CCSID (coded character set identifier) 


currently in effect for the job. If the CCSID of the job is 65535, this buffer is assumed to be 
represented in the default CCSID of the job. 


bufSize (Output) 


The address of the location to store the length of the requested information pointed to by buffer. 


Authorities 


No authorization is required. 


Return Value 


gsk_attribute_get_buffer() 


returns an integer. Possible values are: 
[GSK_OK] 
gsk_attribute_get_buffer() was successful. 


[GSK_ATTRIBUTE_INVALID_ID] 
The specified bufID was not valid. 


[GSK_INVALID_HANDLE] 


The specified handle was not valid. 


[GSK_AS400_ERROR_INVALID_POINTER] 
The buffer or bufSize pointer is not valid. 


[GSK_ERROR_UNSUPPORTED] 
The buffD currently is not supported. 


[GSK_ERROR_IO] 


An error occurred in SSL processing. Check the errno value. 


Error Conditions 


When the gsk_attribute_get_buffer() API fails with return code [GSK_ERROR_IO], errno can be set to: 


[EINTR] Interrupted function call. 
[EDEADLK] Resource deadlock avoided. 
[ETERM] Operation terminated. 


If an errno is returned that is not in this list, look in Errno Values for UNIX-Type Functions for a 
description of the errno. 


Usage Notes 


1. The following GSK_BUF_ID values may be retrieved from the SSL environment after 
gsk_environment_open(). 


o GSK_KEYRING_FILE 

Oo GSK_KEYRING_PW 

o GSK_KEYRING_LABEL 

Oo GSK_OS400_APPLICATION_ID 
Oo GSK_V2_CIPHER_SPECS 

Oo GSK_V3_CIPHER_SPECS 


2. The following GSK_BUF_ID values may be retrieved from the secure session after 
gsk_secure_soc_open(). 


o GSK_KEYRING_LABEL 

Oo GSK_V2_CIPHER_SPECS 

Oo GSK_V3_CIPHER_SPECS 

Oo GSK_CONNECT_SEC_TYPE 

Oo GSK_CONNECT_CIPHER_SPEC 


3. The following GSK_BUF_ID values are defaulted after gsk_secure_soc_open() and will be set for 
the secure session after gsk_secure_soc_init() or gsk_secure_soc_misc(). 


o GSK_CONNECT_SEC_TYPE 
Oo GSK_CONNECT_CIPHER_SPEC 


4. You can reference the buffer pointer as long as the handle for the secure session or the SSL 
environment is still open. 


Related Information 


e gsk attribute_set_bufferQ--Set character information for a secure session or an SSL environment 


e gsk attribute_get_enum()--Get enumerated information about a secure session or a SSL 
environment. 


e gsk attribute_get_numeric_value()--Get numeric information about a secure session or a SSL 
environment 


e esk attribute_get_cert_info(--Get information about a local or partner certificate 


e gsk_environment_close()--Close the SSL environment 


e gsk_environment_init()--Initialize an SSL environment 


e gsk environment_open()--Get a handle for an SSL environment 


e@ gsk secure_soc_close()--Close a secure session 


e@ gsk secure_soc_init()--Negotiate a secure session 


@ gsk secure_soc_misc()--Perform miscellaneous functions for a secure session 


e gsk secure_soc_open()--Get a handle for a secure session 


e gsk _strerror()--Retrieve GSK runtime error message 


API Introduced: V5R1 
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gsk_attribute_get_cert_info()--Get information 
about a local or partner certificate 


Syntax 


#include <gskssl.h> 


int gsk_attribute_get_cert_info(gsk_handle my_gsk_handle, 
GSK_CERT_ID certID, 
const gsk_cert_data_elem **certDataElem, 
int *certDataElemCount) ; 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_attribute_get_cert_info() function is used to obtain specific information about either the server or client 
certificate for a secure session or an SSL environment. 


Parameters 


my_gsk_handle (Input) 


Indicates one of the following handles: 


oO The handle for the secure session. (my_session_handle) 


oO The handle for the SSL environment. (my_env_handle) 


certID (Input) 
Indicates one of the following: 


o GSK_LOCAL_CERT_INFO (701) - Retrieve certificate data information for the local 
certificate that may be sent to the remote connection. This can be retrieved using the SSL 
environment handle or the secure session handle. 


o GSK_PARTNER_CERT_INFO (700) - Retrieve certificate data information for the partner 
certificate that may have been received during the SSL handshake. This can only be retrieved 
using the secure session handle. 


certDataElem (Output) 


The address of a pointer to the certificate information returned from this function call. On output, 
certDataElem will contain the pointer to the information. The storage for this information was allocated 
by the system from user heap storage and will be freed by the gsk_secure_soc_close() API or the 
gsk_environment_close() API. 


certDataElemCount (Output) 


A pointer to an integer that will contain the number of certificate data elements returned from this 
function call. 


Authorities 


No authorization is required. 


Return Value 


gsk_attribute_get_cert_info() returns an integer. Possible values are: 
[GSK_OK] 
gsk_attribute_get_cert_info() was successful. 


[GSK_ATTRIBUTE_INVALID_ID] 


The specified cert/D was not valid. 


[GSK_INVALID_HANDLE] 


The handle passed in to this function was not valid. 


[GSK_INVALID_STATE] 
One of the following occurred: 


oO ASSL environment handle was specified with a certID of GSK_LOCAL_CERT_INFO before a 
gsk_environment_init() has been issued. 


o A secure session handle was specified before a gsk_secure_soc_init() has been issued. 


[GSK_AS400_ERROR_INVALID_POINTER] 


The certDataElem or certDataElemCount pointer is not valid. 


[GSK_INSUFFICIENT_STORAGE] 


Not able to allocate storage for the requested operation. 


[GSK_ERROR_IO] 


An error occurred in SSL processing, check the errno value. 


Error Conditions 


When the gsk_attribute_get_cert_info() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[EINTR] 


Interrupted function call. 


[EDEADLK] 


Resource deadlock avoided. 


[ETERM] 


Operation terminated. 


If an errno is returned that is not in this list, look in Errno Values for UNIX-Type Functions for a description of 
the errno. 


Usage Notes 


1. After gsk_attribute_get_cert_info() returns with a GSK_OK return value, certDataElem points to an 
array of structures of type gsk_cert_data_elem. The following structure is the gsk_cert_data_elem 
structure: 


typedef struct gsk_cert_data_elem_t 
{ 
GSK_CERT_DATA_ID cert_data_id; 
char *cert_data_p; 
int cert _data_l; 


} gsk_cert_data_elem; 


Each element consists of the following fields: 


oO. cert_data_id is the identifier for each element of the certificate. The following are the valid 
identifiers: 


CERT_BODY_DER (600) 
CERT_BODY_BASE64 (601) 
CERT_SERIAL_NUMBER (602) 
CERT_COMMON_NAME (610) 
CERT_LOCALITY (611) 
CERT_STATE_OR_PROVINCE (612) 
CERT_COUNTRY (613) 

CERT_ORG (614) 

CERT_ORG_UNIT (615) 
CERT_DN_PRINTABLE (616) 
CERT_DN_DER (617) 
CERT_POSTAL_CODE (618) 
CERT_EMAIL (619) 
CERT_ISSUER_COMMON_NAME (650) 
CERT_ISSUER_LOCALITY (651) 
CERT_ISSUER_STATE_OR_PROVINCE (652) 
CERT_ISSUER_COUNTRY (653) 
CERT_ISSUER_ORG (654) 
CERT_ISSUER_ORG_UNIT (655) 
CERT_ISSUER_DN_PRINTABLE (656) 
CERT_ISSUER_DN_DER (657) 
CERT_ISSUER_POSTAL_CODE (658) 


m CERT_ISSUER_EMAIL (659) 


oO cert_data_p points to the specific certificate data. 
0 cert_data_I contains the length of the data element. 
2. Many fields are character strings and are terminated with a trailing null. The length does not include the 
null. 


3. Other fields (CERT_BODY_DER, CERT_DN_DER, and so on) may have imbedded nulls and therefore 
must use the integer length for processing. 


4. Not all certificates contain all fields, so the number of fields returned depends on the certificate being 
processed. This open-ended approach means new fields can be added from time to time without 
disrupting existing usage. 


5. All certificate data is returned in ASCII CCSID 850. 


6. You can reference the certDataElem pointers as long as the handle for the secure session or SSL 
environment is open. 


Related Information 


e gsk attribute_get_buffer(Q--Get character information about a secure session or a SSL environment 


e gsk_ attribute_get_enum()--Get enumerated information about a secure session or an SSL environment. 


e@ gsk_attribute_get_numeric_value()--Get numeric information about a secure session or an SSL 
environment 


e gsk environment_close(Q)--Close the SSL environment 


@ gsk_environment_init()--Initialize an SSL environment 


@ gsk_environment_open()--Get a handle for an SSL environment 


e gsk secure_soc_close()--Close a secure session 


@ gsk_secure_soc_init()--Negotiate a secure session 


e@ gsk secure_soc_misc()--Perform miscellaneous functions for a secure session 


@ gsk_secure_soc_open()--Get a handle for a secure session 


e gsk strerror()--Retrieve GSK runtime error message 


API Introduced: V5R1 
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gsk_attribute_get_enum()--Get enumerated 
information about a secure session or an SSL 
environment> 


Syntax 


#include <gskssl.h> 


int gsk_attribute_get_enum(gsk_handle my_gsk_handle, 
GSK_ENUM_ID enumID, 
GSK_ENUM_VALUE *enumValue) ; 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_attribute_get_enum() function is used to obtain values for specific enumerated data for a secure 
session or an SSL environment. 


Parameters 


my_gsk_handle (Input) 
Indicates one of the following handles: 
o The handle for the secure session. (my_session_handle) 


o The handle for the SSL environment. (my_env_handle) 


enumID (Input) 


The following values can be used to retrieve information about the secure session or SSL 
environment that is either defaulted or explicitly set: 


o GSK_PROTOCOL_SSLV2 (403) - Whether the SSL Version 2 protocol is enabled or 
disabled for this secure session or SSL environment. The enumValue returned will be one 
of the following values: 


m GSK_PROTOCOL_SSLV2_ON (510) - SSL Version 2 ciphers are enabled. 
a GSK_PROTOCOL_SSLV2_OFF (511) - SSL Version 2 ciphers are disabled. 


o GSK_PROTOCOL_SSLV3 (404) - Whether the SSL Version 3 protocol is enabled or 
disabled for this secure session or SSL environment. The enumValue returned will be one 
of the following values: 


m GSK_PROTOCOL_SSLV3_ON (512) - SSL Version 3 ciphers are enabled. 


a GSK_PROTOCOL_SSLV3_OFF (513) - SSL Version 3 ciphers are disabled. 


o GSK_PROTOCOL_TLSV1 (407) - Whether the TLS Version 1 protocol is enabled or 
disabled for this secure session or SSL environment. The enumValue returned will be one 
of the following values: 


a GSK_PROTOCOL_TLSV1_ON (518) - TLS Version | ciphers are enabled. 
a GSK_PROTOCOL_TLSV1_OFF (519) - TLS Version 1 ciphers are disabled. 


o GSK_SESSION_TYPE (402) - Type of handshake to be used for this secure session or 
SSL environment. enumValue returned will be one of the following values: 


m GSK_CLIENT_SESSION (507) - Secure sessions act as clients. 


m GSK_SERVER_SESSION (508) - Secure sessions act as a server with no client 
authentication. The client certificate is not requested. 


m GSK_SERVER_SESSION_WITH_CL_AUTH (509) - Secure sessions act as a 
server that requests the client to send a certificate. The value for 
GSK_CLIENT_AUTH_TYPE will determine what happens if the client 
certificate is not valid or not provided. 


o GSK_CLIENT_AUTH_TYPE (401) - Type of client authentication to use for this 
session. enumValue must specify one of the following: 


mg GSK_CLIENT_AUTH_FULL (503) - All received certificates are validated. If a 
certificate that is not valid is received, the secure session does not start, and an 
error code is returned from gsk_secure_soc_init(). 


If no certificate is sent by the client, the start of the secure session is successful. 
Applications can detect this situation by checking the 
GSK_CERTIFICATE_VALIDATION_CODE enumld via 
gsk_attribute_get_numeric value(). A numValue of 
GSK_ERROR_NO_CERTIFICATE will indicate no certificate was sent by client. 
In this case, the application is responsible for the authentication of the client. 


m GSK_CLIENT_AUTH_PASSTHRU (505) - All received certificates are 
validated. If validation is successful or validation fails because the certificate is 
self-signed, expired, or does not have a trusted root, the secure session will start. 
For the other validation failure cases the secure session does not start, and an error 
code is returned from gsk_secure_soc_init(). Applications can detect the situation 
where the secure session started but validation failed by checking the 
GSK_CERTIFICATE_VALIDATION_CODE enumld via 
gsk_attribute_get_numeric value(). The numValue will indicate the certificate 
validation return code for client's certificate. In this situation, the application is 
responsible for the authentication of the client. 


If no certificate is sent by the client, the start of the secure session is successful. 
Applications can detect this situation by checking the 
GSK_CERTIFICATE_VALIDATION_CODE enumild as well. A numValue of 
GSK_ERROR_NO_CERTIFICATE will indicate no certificate was sent by client. 
In this case, the application is also responsible for the authentication of the client. 


m GSK_OS400_CLIENT_AUTH_REQUIRED (6995) - All received certificates 
are validated. If a certificate that is not valid is received, the secure session does 


not start, and an error code is returned from gsk_secure_soc_init(). If no certificate 
is sent by the client, the secure session does not start, and an error code of 
GSK_ERROR_NO_CERTIFICATE is returned from gsk_secure_soc_init(). 


o GSK_PROTOCOL_USED (405) - Which protocol was used for this secure session. The 
enumValue returned will be one of the following values: 


a GSK_PROTOCOL_USED_SSLV2 (514) - The protocol used for this secure 
session is SSL Version 2. 


a GSK_PROTOCOL_USED_SSLV3 (515) - The protocol used for this secure 
session is SSL Version 3. 


a GSK_PROTOCOL_USED_TLSV1 (520) - The protocol used for this secure 
session is TLS Version 1. 


o GSK_SID_FIRST (406) - Whether a full handshake or abbreviated handshake occurred 
for this secure session. The enumValue returned will be one of the following values: 


m GSK_SID_IS_FIRST (516) - A full handshake occurred for this secure session. 


m GSK_SID_NOT_FIRST (517) - An abbreviated handshake occurred for this 
secure session. 


enumValue (Output) 


Specifies a pointer to an integer in which to place the value of the requested information. 


Authorities 


No authorization is required. 


Return Value 


gsk_attribute_get_enum() returns an integer. Possible values are: 
[GSK_OK] 


gsk_attribute_get_enum() was successful. 


[GSK_ATTRIBUTE_INVALID_ID] 


The specified enumID was not valid. 


[GSK_INVALID_HANDLE] 


The specified handle was not valid. 


[GSK_AS400_ERROR_INVALID_POINTER] 


The enumValue pointer is not valid. 


[GSK_ERROR_UNSUPPORTED] 


The enumID is currently not supported. 


[GSK_ERROR_IO] 


An error occurred in SSL processing, check the errno value. 


Error Conditions 


When the gsk_attribute_get_enum() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[EINTR] 


Interrupted function call. 


[EDEADLK] 


Resource deadlock avoided. 
[ETERM] 
Operation terminated. 


If an errno is returned that is not in this list, look in Errno Values for UNIX-Type Functions for a 
description of the errno. 


Usage Notes 


1. The following GSK_ENUM_ID values may be retrieved from the SSL environment after 
gsk_environment_open(). 
o GSK_PROTOCOL_SSLV2 
o GSK_PROTOCOL_SSLV3 
o GSK_PROTOCOL_TLSV1 
o GSK_SESSION_TYPE 
o GSK_CLIENT_AUTH_TYPE 


2. The following GSK_ENUM_ID values may be retrieved from the secure session after 
gsk_secure_soc_open(). 


Oo GSK_PROTOCOL_SSLV2 
GSK_PROTOCOL_SSLV3 
GSK_PROTOCOL_TLSV1 
GSK_PROTOCOL_USED 
GSK_SESSION_TYPE 
GSK_CLIENT_AUTH_TYPE 
GSK_SID_FIRST 


OO 0 0 20 0 


3. The following GSK_ENUM_ID values are defaulted after gsk_secure_soc_open() and will be set 
for the secure session after gsk_secure_soc_init() or gsk_secure_soc_misc(). 


o GSK_PROTOCOL_USED 


o GSK_SID_FIRST 


Related Information 


e gsk attribute_get_bufferQ--Get character information about a secure session or an SSL 
environment 


e gsk attribute_get_numeric_value()--Get numeric information about a secure session or an SSL 
environment 


e gsk_attribute_get_cert_info()--Get information about a local or partner certificate 


e gsk attribute_set_enum()--Set enumerated information for a secure session or an SSL environment 


e@ gsk environment_close()--Close the SSL environment 


e@ gsk environment_initQ--Initialize an SSL environment 


e gsk_ environment_open()--Get a handle for an SSL environment 


e gsk_secure_soc_close()--Close a secure session 


e@ gsk secure_soc_init()--Negotiate a secure session 


e@ gsk secure_soc_misc()--Perform miscellaneous functions for a secure session 


e@ gsk secure_soc_open()--Get a handle for a secure session 


e gsk strerror()--Retrieve GSK runtime error message 


API Introduced: V5R1 
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gsk_attribute_get_numeric_value()--Get 
numeric information about a secure session or 
an SSL environment 


Syntax 


#include <gskssl.h> 
int gsk_attribute_get_numeric_value(gsk_handle my_gsk_handle, 


GSK_NUM_ID numID, 
int *numValue) ; 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_attribute_get_numeric_value() function is used to obtain specific numeric information about a 
secure session or an SSL environment. 


Parameters 


my_gsk_handle (Input) 
Indicates one of the following handles: 
o The handle for the secure session. (my_session_handle) 


o The handle for the SSL environment. (my_env_handle) 


numID (Input) 


The following values can be used to retrieve information about the secure session or the SSL 
environment that is either defaulted or explicitly set: 


oO GSK_FD (300) - numValue is a socket descriptor to be used for this secure session. 


o GSK_V2_SESSION_TIMEOUT (301) - SSL Version 2 session time-out for the 
environment. numValue must be in the range 0-100 seconds. 


o GSK_V3_SESSION_TIMEOUT (302) - SSL Version 3 and TLS version 1 session 
time-out for the environment. numValue must be in the range 0-86400 seconds. 


o GSK_CERTIFICATE_VALIDATION_CODE (6996) - The certificate validation return 
code for the local or peer certificate. 


o GSK_HANDSHAKE_TIMEOUT (6998) - SSL handshake time-out for the secure 
session or the SSL environment. 


numValue (Output) 


A pointer to an integer containing the value of the requested information. 


Authorities 


No authorization is required. 


Return Value 


gsk_attribute_get_numeric_value() returns an integer. Possible values are: 
[GSK_OK] 


gsk_attribute_get_numeric_value() was successful. 


[GSK_ATTRIBUTE_INVALID_ID] 


The specified numID was not valid. 


[GSK_INVALID_HANDLE] 


The handle specified was not valid. 


[GSK_AS400_ERROR_INVALID_POINTER] 


The numValue pointer is not valid. 


[GSK_ERROR_UNSUPPORTED] 


The numID is currently not supported. 


[GSK_ERROR_IO] 


An error occurred in SSL processing, check the errno value. 


Error Conditions 


When the gsk_attribute_get_numeric_value() API fails with return code [GSK_ERROR_IO], errno can 
be set to: 


[EINTR] 


Interrupted function call. 


[EDEADLK] 


Resource deadlock avoided. 


[ETERM] 


Operation terminated. 


If an errno is returned that is not in this list, look in Errno Values for UNIX-Type Functions for a 
description of the errno. 


p> 
Usage Notes 


1. The following GSK_NUM_ID values may be retrieved from the SSL environment after 
gsk_environment_open(): 


Oo GSK_V2_SESSION_TIMEOUT 
Oo GSK_V3_SESSION_TIMEOUT 
o GSK_HANDSHAKE_TIMEOUT 


2. The following GSK_NUM_ID value may be retrieved from the SSL environment after 
gsk_environment_init(). 


o GSK_CERTIFICATE_VALIDATION_CODE - Will return the certificate validation 


return code for the local certificate. 


3. The following GSK_NUM_ID value may be retrieved from each individual secure session after 


gsk_secure_soc_init(). 


o GSK_CERTIFICATE_VALIDATION_CODE - Will return the certificate validation 


return code for the peer's certificate. 


4. The following GSK_NUM_ID values may be retrieved from each individual secure session after 


gsk_secure_soc_open(). 
o GSK_FD 
o GSK_HANDSHAKE_TIMEOUT 


5. The following GSK_NUM_ID values are currently not supported in the OS/400 implementation: 


Oo GSK_V2_SIDCACHE_SIZE 
Oo GSK_V3_SIDCACHE_SIZE 
o GSK_LDAP_SERVER_PORT 


Related Information 


e gsk attribute_get_bufferQ--Get character information about a secure session or an SSL 
environment 


e gsk attribute_get_enum()--Get enumerated information about a secure session or an SSL 
environment. 


gsk_attribute_get_cert_info()--Get information about a local or partner certificate 


e gsk_attribute_set_numeric_value()--Set numeric information for a secure session or an SSL 


environment 


gsk_environment_init()--Initialize an SSL environment 


e@ gsk environment_open()--Get a handle for an SSL environment 


gsk_secure_soc_initQ)--Negotiate a secure session 


e@ gsk_secure_soc_misc()--Perform miscellaneous functions for a secure session 


@ gsk_secure_soc_open()--Get a handle for a secure session 


gsk_strerror(Q--Retrieve GSK runtime error message 


API Introduced: V5R1 
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gsk_attribute_set_buffer()--Set character 
information for a secure session or an SSL 
environment 


Syntax 


#include <gskssl.h> 


int gsk_attribute_set_buffer(gsk_handle my_gsk_handle, 
GSK_BUF_ID bufID, 
const char *buffer, 
int bufSize); 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_attribute_set_buffer() function is used to set a specified buffer attribute to a value inside the 
specified secure session or SSL environment. 


Parameters 


my_gsk_handle (Input) 
Indicates one of the following handles: 
o The handle for the secure session. (my_session_handle) 


o The handle for the SSL environment. (my_env_handle) 


bufID (Input) 


Indicates one of the following operations: 


o GSK_KEYRING_FILE (201) - buffer points to the name of the certificate store file to be 
used for the secure session or SSL environment. Authority to the certificate store file will 
be checked on the gsk_environment_init() API or the gsk_secure_soc_init() API. 


o GSK_KEYRING_PW (202) - buffer points to the password for the certificate store file to 
be used for the secure session or SSL environment. 


o GSK_KEYRING_LABEL (203) - buffer points to the certificate label associated with the 
certificate in the certificate store to be used for the secure session or SSL environment. 


o GSK_OS400_APPLICATION_ID (6999) - buffer points to the application identifier to be 


used for the SSL environment. 


o GSK_V2_CIPHER_SPECS (205) - buffer points to the list of SSL Version 2 ciphers to be 
used for the secure session or the SSL environment. 


o GSK_V3_CIPHER_SPECS (206) - buffer points to the list of SSL Version 3/TLS 
Version | ciphers to be used for the secure session or the SSL environment. 


buffer (Input) 


A pointer to the information to be used for the secure session or the SSL environment. 


The data in the buffer is assumed to be represented in the CCSID (coded character set identifier) 
currently in effect for the job. If the CCSID of the job is 65535, this buffer is assumed to be 
represented in the default CCSID of the job. 


bufSize (Input) 


The length of the buffer information. If bufSize is specified as 0, the length of bufSize will be 
calculated. 


Authorities 


No authorization is required. 


Return Value 


gsk_attribute_set_buffer() returns an integer. Possible values are: 
[GSK_OK] 


gsk_attribute_set_buffer() was successful. 


[GSK_ATTRIBUTE_INVALID_ID] 
The bufID value is not a valid identifier. 


[GSK_ATTRIBUTE_INVALID_LENGTH] 
The bufSize specified or the length of buffer is not valid. 


[GSK_INVALID_HANDLE] 


my_gsk_handle is not a valid handle that was received from issuing gsk_environment_open() or 
gsk_secure_soc_open(). 


[GSK_AS400_ERROR_INVALID_POINTER] 
The buffer pointer is not valid. 


[GSK_INVALID_STATE] 
One of the following occurred: 


oO buffD cannot be set for a SSL environment after a gsk_environment_init() has been 


issued. 


oO. buffD cannot be set for a secure session after a gsk_secure_soc_init() has been issued. 


[GSK_ERROR_UNSUPPORTED] 
The buffD value is currently not supported. 


[GSK_INSUFFICIENT_STORAGE] 


Not able to allocate storage for the requested operation. 


[GSK_ERROR_IO] 


An error occurred in SSL processing, check the errno value. 


Error Conditions 


When the gsk_attribute_set_buffer() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[EINTR] 


Interrupted function call. 


[EDEADLK] 


Resource deadlock avoided. 
[ETERM] 
Operation terminated. 


If an errno is returned that is not in this list, look in Errno Values for UNIX-Type Functions for a 
description of the errno. 


Usage Notes 


1. The following GSK_BUF_ID values may be set in the SSL environment after 
gsk_environment_open() and before gsk_environment_init(). They are used as defaults for 
subsequent secure sessions: 


GSK_KEYRING_FILE 
GSK_KEYRING_PW 
GSK_KEYRING_LABEL 
GSK_OS400_APPLICATION_ID 
GSK_V2_CIPHER_SPECS 
GSK_V3_CIPHER_SPECS 


OO 0 0 0 0 


2. The following GSK_BUF_ID values may be set for each individual secure session after 
gsk_secure_soc_open() and before gsk_secure_soc_init(). These values will override values set in 
the SSL environment: 


o GSK_KEYRING_ LABEL 
o GSK_V2_CIPHER_SPECS 
Oo GSK_V3_CIPHER_SPECS 


3. The following GSK_V3_CIPHER_SPECS values are the SSL Version 3 ciphers and the TLS 
Version | ciphers supported: 


01 = NULL MD5 

02 = NULL SHA 

03 = RC4 MD5 EXPORT 

04 = RC4 MD5 US 

05 = RC4 SHA US 

06 = RC2 MD5 EXPORT 

09 = DES SHA EXPORT 

OA = Triple DES SHA US 

2F = AES SHA US 

NULL = Default cipher specs are used (may change in future) 
For AC3 = '04050A090306'! 
For AC2 = '090306' 


4. The following GSK_V2_CIPHER_SPECS values are the SSL Version 2 ciphers supported: 


YN BWNHE 
ll 


NULL 


RC4 
RC4 
RC2 
RC2 
DES 


US 
EXPORT 
US 
EXPORT 
56-bit 


Triple DES US 


Default cipher specs are used (may change in future) 


For AC3 = '136724' 
For AC2 = '624' 


5. The following GSK_BUF_ID values currently are not supported in the OS/400 implementation: 


O 0 0 0 


GSK_KEYRING_STASH_FILE 
GSK_LDAP_SERVER 
GSK_LDAP_USER 
GSK_LDAP_USER_PW 


6. The following are the possible scenerios for the use of GSK_KEYRING_LABEL: 


o GSK_KEYRING_LABEL can be set after gsk_environment_open() and before 
gsk_environment_init() to indicate which certificate in the GSK_KEYRING_FILE to 
use for the secure environment. 


o GSK_KEYRING_LABEL can be set after gsk_secure_soc_open() and before 
gsk_secure_soc_init() to indicate which certificate in the GSK_KEYRING_FILE to use 
for the secure session. 


o If GSK_KEYRING_LABEL is not set, the default certificate label in the 


GSK_KEYRING_FILE is used for the SSL environment. 


7. If GSK_OS400_APPLICATION_ID is set, the GSK_KEYRING_FILE, the 
GSK_KEYRING_LABEL, and the GSK_KEYRING_PASSWORD values are ignored. 


Related Information 


e gsk attribute_get_buffer(--Get character information about a secure session or an SSL 


environment 


e gsk_ attribute_set_enum()--Set enumerated information for a secure session or an SSL environment. 


e gsk attribute_set_numeric_value()--Set numeric information for a secure session or an SSL 
environment 


e gsk_environment_init()--Initialize an SSL environment 


e gsk environment_open()--Get a handle for an SSL environment 


@ gsk secure_soc_init()--Negotiate a secure session 


e@ gsk secure_soc_misc()--Perform miscellaneous functions for a secure session 


e@ gsk secure_soc_open()--Get a handle for a secure session 


e gsk_strerror()--Retrieve GSK runtime error message 
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gsk_attribute_set_enum()--Set enumerated 
information for a secure session or an SSL 
environment 


Syntax 


#include <gskssl.h> 


int gsk_attribute_set_enum(gsk_handle my_gsk_handle, 
GSK_ENUM_ID enumID, 
GSK_ENUM_VALUE enumValue) ; 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_attribute_set_enum() function is used to set a specified enumerated type attribute to an 
enumerated value in the secure session or SSL environment. 


Parameters 


my_gsk_handle (Input) 
Indicates one of the following handles: 
o The handle for the secure session. (my_session_handle) 


o The handle for the SSL environment. (my_env_handle) 


enumID (Input) 


Indicates one of the following operations: 


o GSK_PROTOCOL_SSLYV2 (403) - Enables or disables the SSL Version 2 protocol. 
enumValue must specifiy one of the following: 


a GSK_PROTOCOL_SSLV2_ON (510) - Enable SSL Version 2 ciphers. 
a GSK_PROTOCOL_SSLV2_OFF (511) - Disable SSL Version 2 ciphers. 


o GSK_PROTOCOL_SSLYV3 (404) - Enables or disables the SSL Version 3 protocol. 
enumValue must specifiy one of the following: 


a GSK_PROTOCOL_SSLV3_ON (512) - Enable SSL Version 3 ciphers. 
= GSK_PROTOCOL_SSLV3_OFF (513) - Disable SSL Version 3 ciphers. 


o GSK_PROTOCOL_TLSV1 (407) - Enables or disables the TLS Version 1| protocol. 
enumValue must specifiy one of the following: 


m GSK_PROTOCOL_TLSV1_ON (518) - Enable TLS Version 1 ciphers. 
a GSK_PROTOCOL_TLSV1_OFF (519) - Disable TLS Version 1 ciphers. 


o GSK_SESSION_TYPE (402) - Type of handshake to be used for this secure session or 
SSL environment. enumValue must specifiy one of the following operations: 


m GSK_CLIENT_SESSION (507) - Secure sessions act as clients. 
m GSK_SERVER_SESSION (508) - Secure sessions act as a server with no client 


authentication. The client is not asked for a certificate. 


m GSK_SERVER_SESSION_WITH_CL_AUTH (509) - Secure sessions act as a 


server that requests the client to send a certificate. The value for 
GSK_CLIENT_AUTH_TYPE will determine what happens if the client 
certificate is not valid or not provided. 


o GSK_CLIENT_AUTH_TYPE (401) - Type of client authentication to use for this 
session. enumValue must specify one of the following: 


enumValue (Input) 


mw GSK_CLIENT_AUTH_FULL (503) - All received certificates are validated. If 


an invalid certificate is received, the secure session does not start, and an error 
code is returned from gsk_secure_soc_init(). 


If no certificate is sent by the client, the start of the secure session is successful. 
Applications can detect this situation by checking the 
GSK_CERTIFICATE_VALIDATION_CODE enumld through 
gsk_attribute_get_numeric value(). A numValue of 
GSK_ERROR_NO_CERTIFICATE will indicate no certificate was sent by client. 
In this case, the application is responsible for the authentication of the client. 


GSK_CLIENT_AUTH_PASSTHRU (505) - All received certificates are 
validated. If validation is successful or validation fails because the certificate is 
self-signed, expired, or does not have a trusted root, the secure session will start. 
For the other validation failure cases the secure session does not start, and an error 
code is returned from gsk_secure_soc_init(). Applications can detect the situation 
where the secure session started but validation failed by checking the 
GSK_CERTIFICATE_VALIDATION_CODE enumld via 
gsk_attribute_get_numeric value(). The numValue will indicate the certificate 
validation return code for client's certificate. In this situation, the application is 
responsible for the authentication of the client. 


If no certificate is sent by the client, the start of the secure session is successful. 
Applications can detect this situation by checking the 
GSK_CERTIFICATE_VALIDATION_CODE enumild as well. A numValue of 
GSK_ERROR_NO_CERTIFICATE will indicate no certificate was sent by client. 
In this case, the application is also responsible for the authentication of the client. 


GSK_OS400_CLIENT_AUTH_REQUIRED (6995) - All received certificates 
are validated. If a certificate that is not valid is received, the secure session does 
not start, and an error code is returned from gsk_secure_soc_init(). If no certificate 
is sent by the client, the secure session does not start, and an error code of 
GSK_ERROR_NO_CERTIFICATE is returned from gsk_secure_soc_init(). 


An enumerated type appropiate to the enumID. 


Authorities 


No authorization is required. 


Return Value 


gsk_attribute_set_enum() returns an integer. Possible values are: 
[GSK_OK] 


gsk_attribute_set_enum() was successful. 


[GSK_ATTRIBUTE_INVALID_ENUMERATION] 


The enumeration specified for the enumValue was not valid. 


[GSK_ATTRIBUTE_INVALID_ID] 


The enumID specified was not valid. 


[GSK_INVALID_STATE] 
One of the following occurred: 
o The enumID cannot be set after a gsk_environment_init() has been issued. 


o The enumID cannot be set after a gsk_secure_soc_init() has been issued. 


[GSK_INVALID_HANDLE] 


The handle specified was not valid. 


[GSK_ERROR_UNSUPPORTED] 


The enumID is currently not supported. 


[GSK_ERROR_IO] 


An error occurred in SSL processing, check the errno value. 


Error Conditions 


When the gsk_attribute_set_enum() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[EINTR] 


Interrupted function call. 


[EDEADLK] 


Resource deadlock avoided. 


[ETERM] 


Operation terminated. 


If an errno is returned that is not in this list, look in Errno Values for UNIX-Type Functions for a 
description of the errno. 


Usage Notes 


1. The following GSK_ENUM_ID values may be set in the SSL environment after 
gsk_environment_open() and before gsk_environment_init(). They are used as defaults for 
subsequent secure sessions: 


GSK_PROTOCOL_SSLV2 
GSK_PROTOCOL_SSLV3 
GSK_PROTOCOL_TLSV1 
GSK_SESSION_TYPE 
GSK_CLIENT_AUTH_TYPE 


O 0 0 0 O 


2. The following GSK_ENUM_ID values may be set for each individual secure session after 
gsk_secure_soc_open() and before gsk_secure_soc_init(). These values will override values set in 
the SSL environment: 


GSK_PROTOCOL_SSLV2 
GSK_PROTOCOL_SSLV3 
GSK_PROTOCOL_TLSV1 
GSK_SESSION_TYPE 
GSK_CLIENT_AUTH_TYPE 


OO 0 0 0 


Related Information 


e esk attribute_get_enum()--Get enumerated information about a secure session or an SSL 
environment. 


e gsk _attribute_set_bufferQ--Set character string information for a secure session or an SSL 
environment. 


e gsk attribute_set_numeric_value()--Set numeric information for a secure session or an SSL 
environment 


e gsk_environment_init()--Initialize an SSL environment 


e gsk environment_open()--Get a handle for an SSL environment 


@ gsk secure_soc_init()--Negotiate a secure session 


e@ gsk_secure_soc_misc()--Perform miscellaneous functions for a secure session 


@ gsk_secure_soc_open()--Get a handle for a secure session 


e gsk_strerrorQ--Retrieve GSK runtime error message 


API Introduced: V5R1 
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gsk_attribute_set_numeric_value()--Set 
numeric information for a secure session or an 
SSL environment 


Syntax 


#include <gskssl.h> 
int gsk_attribute_set_numeric_value(gsk_handle my_gsk_handle, 


GSK_NUM_ID numID, 
int numValue); 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_attribute_set_numeric_value() function is used to set specific numeric information for a secure 
session or an SSL environment. 


Parameters 


my_gsk_handle (Input) 
One of the following handles: 
o The handle for the secure session. (my_session_handle) 


o The handle for the SSL environment. (my_env_handle) 


numID (Input) 


One of the following operations: 
oO GSK_FD (300) - numValue is a socket descriptor to be used for this secure session. 


o GSK_V2_SESSION_TIMEOUT (301) - numValue is the SSL Version 2 session time-out 
for the SSL environment. numValue must be in the range 0-100 seconds. 


o GSK_V3_SESSION_TIMEOUT (302) - numValue is the SSL Version 3 and TLS 
Version | session time-out for the SSL environment. numValue must be in the range 
0-86400 seconds (24 hours). 


o GSK_HANDSHAKE_TIMEOUT (6998) - numValue is the SSL handshake time-out for 
the secure session or the SSL environment. numValue must be in seconds. A numValue of 
0 is the default which means to wait forever. 


numValue (Input) 


An integer value to be updated for the specified numID. 


Authorities 


No authorization is required. 


Return Value 


gsk_attribute_set_numeric_value() returns an integer. Possible values are: 
[GSK_OK] 


gsk_attribute_set_numeric_value() was successful. 


[GSK_INVALID_STATE] 
One of the following occurred: 


oO numID cannot be set in the SSL environment after a gsk_environment_init() has been 
issued. 


o numID cannot be set for a secure session after a gsk_secure_soc_init() has been issued. 


[GSK_ATTRIBUTE_INVALID_ID] 


The numID specified was not valid. 


[GSK_ATTRIBUTE_INVALID_NUMERIC_VALUE] 


The numValue specified was not valid. 


[GSK_INVALID_HANDLE] 


A handle was specified that was not valid. 


[GSK_ERROR_UNSUPPORTED] 


The numID is currently not supported. 


[GSK_ERROR_IO] 


An error occurred in SSL processing, check the errno value. 


Error Conditions 


When the gsk_attribute_set_numeric_value() API fails with return code [GSK_ERROR_IO], errno can 
be set to: 


[EINTR] 


Interrupted function call. 


[EDEADLK] 


Resource deadlock avoided. 


[ETERM] 


Operation terminated. 


If an errno is returned that is not in this list, look in Errno Values for UNIX-Type Functions for a 
description of the errno. 


Usage Notes 


1. The following GSK_NUM_ID values may be set in the SSL environment after 
gsk_environment_open() and before gsk_environment_init(). They are used as defaults for 
subsequent secure sessions: 


Oo GSK_V2_SESSION_TIMEOUT 
oO GSK_V3_SESSION_TIMEOUT 
o GSK_HANDSHAKE_TIMEOUT 


2. The following GSK_NUM_ID values may be set for each individual secure session after 
gsk_secure_soc_open() and before gsk_secure_soc_init(). These values will override values set in 
the SSL environment: 


o GSK_FD 
o GSK_HANDSHAKE_TIMEOUT 


3. The following GSK_NUM_ID values are currently not supported in the OS/400 implementation: 
o GSK_V2_SIDCACHE_ SIZE 
o GSK_V3_SIDCACHE_SIZE 
o GSK_LDAP_SERVER_PORT 


4. The GSK_FD value is a socket descriptor that must have an address family of AF_INET 2 or 
AF_INET6%. and a socket type of SOCK_STREAM. 


Related Information 


e gsk attribute_get_numeric_value()--Get numeric information about a secure session or an SSL 
environment 


e gsk _attribute_set_buffer()--Set character string information for a secure session or an SSL 


environment. 


gsk_attribute_set_enum()--Set enumerated information for a secure session or an SSL environment. 


e gsk environment_init()--Initialize an SSL environment 


e osk environment_open()--Get a handle for an SSL environment 


gsk_secure_soc_initQ--Negotiate a secure session 


gsk_secure_soc_misc()--Perform miscellaneous functions for a secure session 


gsk_secure_soc_open()--Get a handle for a secure session 


gsk_strerror()--Retrieve GSK runtime error message 


API Introduced: V5R1 
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gsk_environment_close()--Close an SSL 
environment 


Syntax 


#include <gskssl.h> 


int gsk_environment_close(gsk_handle *my_env_handle) ; 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_environment_close() function is used to close the SSL environment and release all storage 
associated with the environment. 


Parameters 


my_env_handle (Input) 


A pointer to the handle for the SSL environment to be closed. 


Authorities 


No authorization is required. 


Return Value 


gsk_environment_close() returns an integer. Possible values are: 
[GSK_OK] 


gsk_environment_close() was successful. 


[GSK_CLOSE_FAILED] 


An error occurred during close processing. 


[GSK_INVALID_HANDLE] 


The handle specified was not valid. 


[GSK_AS400_ERROR_INVALID_POINTER] 


my_env_handle pointer is not valid. 


[GSK_ERROR_IO] 


An error occurred in SSL processing, check the errno value. 


Error Conditions 


When the gsk_environment_close() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[EINTR] 


Interrupted function call. 


[EDEADLK] 


Resource deadlock avoided. 
[ETERM] 
Operation terminated. 


If an errno is returned that is not in this list, look in Errno Values for UNIX-Type Functions for a 
description of the errno. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. You should close all secure sessions using the SSL environment prior to doing the 
gsk_environment_close(). 


2. If gsk_environment_close() is issued prior to all secure sessions being closed, the active secure 
sessions will continue to work. The resources for the SSL environment will not be freed up until 
after the last secure session closes. No new secure sessions will be allowed to start using the closed 
SSL environment. 


Related Information 
e gsk_environment_init()--Initialize an SSL environment 


e@ gsk_environment_open()--Get a handle for an SSL environment 


e@ gsk_secure_soc_close()--Close a secure session 


@ gsk secure_soc_init()--Negotiate a secure session 


@ gsk secure_soc_open()--Get a handle for a secure session 


gsk_strerror(--Retrieve GSK runtime error message 


API Introduced: V5R1 


Top | UNIX-Type APIs | APIs by category 


gsk_environment_init()--Initialize an SSL 
environment 


Syntax 


#include <gskssl.h> 


int gsk_environment_init (gsk_handle my_env_handle) ; 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_environment_init() function is used to initialize the SSL environment after any required attributes 
are set. The certificate store file is opened and other operations such as accessing information in the 
registration facility are performed to set up this environment. After this function call is issued, SSL is ready 
to process secure session requests. 


Parameters 


my_env_handle (Input) 
The handle identifying the SSL environment that will be initialized. 


Authorities 


Authorization of *R (allow access to the object) to the certificate store file and its associated files is 
required. Authorization of *X (allow use of the object) to each directory of the path name of the certificate 
store file and its associated files is required. 


Return Value 


gsk_environment_init() returns an integer. Possible values are: 
[GSK_OK] 


gsk_environment_init() was successful. 


[GSK_INVALID_HANDLE] 


The handle specified was not valid. 


[GSK_INVALID_STATE] 


A gsk_environment_init() has already been issued with this handle. 


[GSK_KEYRING_OPEN_ERROR] 


Certificate store file could not be opened. 


[GSK_AS400_ERROR_NO_ACCESS] 


No permission to access the certificate store file. 


[GSK_ERROR_BAD_V3_CIPHER] 
An SSLV3 or TLSV1 cipher suite was specified that is not valid. 


[GSK_ERROR_BAD_V2_CIPHER] 
An SSLV2 cipher suite was specified that is not valid. 


[GSK_ERROR_BAD_CERTIFICATE] 


The certificate is bad. 


[GSK_ERROR_NO_PRIVATE_KEY] 


There is no private key associated with the certificate. 


[GSK_AS400_ERROR_PASSWORD_EXPIRED] 


The validity time period of the certificate store file password has expired. 


[GSK_ERROR_BAD_KEYFILE_LABEL] 


The specified certificate store's certificate label is not valid or does not exist. 


[GSK_ERROR_BAD_KEYFILE_PASSWORD] 


The specified certificate store password is not valid. 


[GSK_NO_KEYFILE_PASSWORD] 


No certificate store password was specified. 


[GSK_AS400_ERROR_NOT_REGISTERED] 


The application identifier has not been registered. 


[GSK_AS400_ERROR_INVALID_POINTER] 


my_env_handle pointer is not valid. 


[GSK_ERROR_BAD_KEY_LEN_FOR_EXPORT] 


The certificate was created with a key length that cannot be exported. 


[GSK_INSUFFICIENT_STORAGE] 


Not able to allocate storage for the requested operation. 


[GSK_INTERNAL_ERROR] 


An unexpected error occurred during SSL processing. 


[GSK_ERROR_IO] 


An error occurred in SSL processing, check errno value. 


Error Conditions 


When the gsk_environment_init() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[EINTR] 


Interrupted function call. 


[EDEADLK] 


Resource deadlock avoided. 


[ETERM] 


Operation terminated. 


If an errno is returned that is not in this list, look in Errno Values for UNIX-Type Functions for a 
description of the errno. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. If gsk_environment_init() fails, gsk_environment_close() must be issued to clean up resources. 


2. Multiple SSL environment handles may be opened in a process with different attributes set for each 
SSL environment. 


3. The status of the local certificate can be determined by checking the 
GSK_CERTIFICATE_VALIDATION_CODE enumild using gsk_attribute_get_numeric_value(). 
The numValue will indicate the certificate validation return code for the certificate used on this 
gsk_environment_init(). 


Related Information 


gsk_attribute_set_buffer(Q)--Set character information for a secure session or an SSL environment. 


gsk_attribute_set_enum()--Set enumerated information for a secure session or an SSL environment. 


gsk_attribute_set_numeric_value()--Set numeric information for a secure session or an SSL 
environment 


gsk_environment_close()--Close the SSL environment 


gsk_environment_open()--Get a handle for an SSL environment 


gsk_strerror()--Retrieve GSK runtime error message 
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gsk_environment_open()--Get a handle for an 
SSL environment 


Syntax 


#include <gskssl.h> 


int gsk_environment_open(gsk_handle *my_env_handle); 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_environment_open() function is used to get storage for the SSL environment. This function call 
must be issued before any other gsk function calls are issued. This call returns an SSL environment handle 
that must be saved and used on subsequent gsk calls. 


Parameters 


my_env_handle (Output) 


A pointer to the SSL environment handle to be used for subsequent gsk function calls. 


Authorities 


No authorization is required. 


Return Value 


gsk_environment_open() returns an integer. Possible values are: 
[GSK_OK] 


gsk_environment_open() was successful. 


[GSK_API_NOT_AVAILABLE] 
One of the following software products is not installed: 
1. Digital Certificate Manager (DCM), 57xx-SS1 - OS400 Option 34 
2. Cryptographic Access Provider, 57xx-ACy 


(where xx is equal to the current OS/400 product ID and y is equal to one of the current 
available level of Cryptographic Access Provider licensed program products.) 


[GSK_INSUFFICIENT_STORAGE] 


Not able to allocate storage for the requested operation. 


[GSK_INTERNAL_ERROR] 


An internal error occured during system processing. 


[GSK_AS400_ERROR_INVALID_POINTER] 


The my_env_handle pointer is not valid. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. After gsk_environment_open() returns with a GSK_OK return value, attributes for the SSL 
environment have been set and can be retrieved using any of the get function calls. The following is 
a list of the defaulted values: 


o GSK_V2_SESSION_TIMEOUT set to 100 seconds. 

GSK_V3_SESSION_TIMEOUT set to 86400 seconds (24 hours). 
GSK_HANDSHAKE_TIMEOUT set to 0 (wait forever). 

GSK_SESSION_TYPE set to GSK_CLIENT_SESSION. 

GSK_KEYRING_LABEL set to use the default certificate from the certificate store file. 
GSK_PROTOCOL_TLSV1 set to GSkK_PROTOCOL_TLSV1_ON. 
GSK_PROTOCOL_SSLV3 set to GSK_PROTOCOL_SSLV3_ON. 
GSK_PROTOCOL_SSLV2 set to GSK_PROTOCOL_SSLV2_ON. 


GSK_V2_CIPHER_SPECS set to the default SSL Version 2 cipher suite list based on the 
product installed. 


GSK_V3_CIPHER_SPECS set to the default SSL Version 3 cipher suite list based on the 
product installed. 
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2. The default cipher suite list associated with the installed Cryptographic Access Provider, 57xx-AC3 
(US) product in preference order is as follows: 


o GSK_V3_CIPHER_SPECS set to SSL Version 3 or TLS Version 1 default 
"2F04050A090306." 


o GSK_V2_CIPHER_SPECS set to "137624." 


See the usage notes in gsk_attribute_set_buffer() API for the format of the ciphers. 


3. The default cipher suite list associated with the installed Cryptographic Access Provider, 57xx-AC2 
(International) product in preference order is as follows: 


o GSK_V3_CIPHER_SPECS set to SSL Version 3 or TLS Version 1 default "090306." 
o GSK_V2_CIPHER_SPECS set to "624." 


See the usage notes in gsk_attribute_set_buffer() API for the format of the ciphers. 


Related Information 


e gsk attribute_set_bufferQ--Set character information for an secure session or a SSL environment 


e gsk_attribute_set_enum()--Set enumerated information for a secure session or an SSL environment 


e esk attribute_set_numeric_value()--Set numeric information for a secure session or an SSL 
environment 


e gsk_environment_close()--Close the SSL environment 


e gsk_environment_init()--Initialize an SSL environment 


gsk_strerrorQ--Retrieve GSK runtime error message 
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gsk_secure_soc_close()--Close a secure 
session 


Syntax 


#include <gskssl.h> 


int gsk_secure_soc_close(gsk_handle *my_session_handle) ; 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_secure_soc_close() function is used to close a secure session and free all the associated resources 
for that secure session. 


Parameters 


my_session_handle (Input) 


A pointer to the handle for the secure session to be closed. This handle originated from a call to 
gsk_secure_soc_open(). 


Authorities 


No authorization is required. 


Return Value 


gsk_secure_soc_close() returns an integer. Possible values are: 
[GSK_OK] 


gsk_secure_soc_close() was successful. 


[GSK_CLOSE_FAILED] 


An error occurred during close processing. 


[GSK_INVALID_HANDLE] 


The handle specified was not valid. 


[GSK_ERROR_IO] 


An error occurred in SSL processing, check the errno value. 


Error Conditions 


When the gsk_secure_soc_close() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[EINTR] 


Interrupted function call. 


[EDEADLK] 


Resource deadlock avoided. 


[ETERM] 


Operation terminated. 


If an errno is returned that is not in this list, look in Errno Values for UNIX-Type Functions for a 
description of the errno. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. You must do a gsk_secure_soc_close() if a prior gsk_secure_soc_open() was successful. 


Related Information 


e@ gsk secure_soc_init()--Negotiate a secure session 


e gsk secure _soc_misc()--Perform miscellaneous functions for a secure session 


e@ gsk secure_soc_open()--Get a handle for a secure session 


e gsk _strerror()--Retrieve GSK runtime error message 
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gsk_secure_soc_init()--Negotiate a secure 
session 


Syntax 


#include <gskssl.h> 


int gsk_secure_soc_init(gsk_handle my_session_handle) ; 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_secure_soc_init() function is used to negotiate a secure session, using the attributes set for the 
SSL environment and the secure session. This API does the SSL handshake to the remote peer; upon 
successful completion, you have a secure session established. 


Parameters 


my_session_handle (Input) 


The handle for this secure session that was obtained through the gsk_secure_soc_open() API call. 


Authorities 


Authorization of *R (allow access to the object) to the certificate store file and its associated files is 
required. Authorization of *X (allow use of the object) to each directory of the path name of the certificate 
store file and its associated files is required. 


Return Value 


gsk_secure_soc_init() returns an integer. Possible values are: 
[GSK_OK] 


gsk_secure_soc_init() was successful. 


[GSK_INVALID_HANDLE] 


The handle specified was not valid. 


[GSK_KEYRING_OPEN_ERROR] 


Certificate store file could not be opened. 


[GSK_ERROR_BAD_KEYFILE_LABEL] 


The specified certificate store label is not valid. 


[GSK_ERROR_BAD_V3_CIPHER] 
An SSLV3 or TLSV1 cipher suite was specified that is not valid. 


[GSK_ERROR_BAD_V2_CIPHER] 
An SSLV2 cipher suite was specified that is not valid. 


[GSK_ERROR_NO_CIPHERS] 


No ciphers available or no ciphers were specified. 


[GSK_ERROR_NO_CERTIFICATE] 


No certificate is available for SSL processing. 


[GSK_ERROR_BAD_CERTIFICATE] 


The certificate is bad. 


[SSL_ERROR_NOT_TRUSTED_ROOT] 


The certificate is not signed by a trusted certificate authority. 


[GSK_KEYFILE_CERT_EXPIRED] 


The validity time period of the certificate has expired. 


[GSK_ERROR_BAD_MESSAGE] 


A badly formatted message was received. 


[GSK_ERROR_UNSUPPORTED] 
Operation is not supported by SSL. 


[GSK_ERROR_BAD_PEER] 


The peer system is not recognized. 


[GSK_ERROR_ CLOSED] 
The SSL session ended. 


[GSK_AS400_ERROR_NO_INITIALIZE] 


A successful gsk_environment_init() was not previously called with this handle. 


[GSK_AS400_ERROR_TIMED_OUT] 
The value specified for the handshake timeout expired before the handshake completed. 


[GSK_AS400_ERROR_NOT_TCP] 


The socket descriptor type is not SOCK_STREAM or the address family is not AF_INET#* or 
AF_INET6*. 


[GSK_AS400_ERROR_ALREADY_SECURE] 


The socket descriptor is already in use by another secure session. 


[GSK_INSUFFICIENT_STORAGE] 


Unable to allocate storage for the requested operation. 


[GSK_AS400_ERROR_INVALID_POINTER] 


The my_session_handle pointer is not valid. 


[GSK_INTERNAL_ERROR] 


An unexpected error occurred during SSL processing. 


[GSK_ERROR_IO] 


An error occurred in SSL processing, check errno value. 


Error Conditions 


When the gsk_secure_soc_init() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[EIO] 


Input/output error. 


[EINTR] 


Interrupted function call. 


[EDEADLK] 


Resource deadlock avoided. 


[ETERM] 


Operation terminated. 
[EUNATCH] 
The protocol required to support the specified address family is not available at this time. 


Any errno that can be returned by send(Q) or recv() can be returned by this API. See Sockets APIs for a 
description of the errno values they return. 


If an errno is returned that is not in this list, see Errno Values for UNIX-Type Functions for a description of 


the errno. 


Usage Notes 


1. The gsk_secure_soc_init() function is valid only on sockets that have an address family of 
AF_INET 2 or AF_INET6%S and a socket type of SOCK_STREAM. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Related Information 


e gsk attribute_set_bufferQ--Set character information for a secure session or an SSL environment. 


e gsk attribute_set_enum()--Set enumerated information for a secure session or an SSL environment. 


e gsk_attribute_set_numeric_value()--Set numeric information for a secure session or an SSL 


environment 


e gsk secure_soc_close()--Close a secure session 


e@ gsk secure_soc_misc()--Perform miscellaneous functions for a secure session 


e@ gsk secure_soc_open()--Get a handle for a secure session 


e gsk_ secure_soc_read()--Receive data on a secure session 


ef} 


e@ gsk secure_soc_startInit(Q)--Start asynchronous operation to negotiate a secure session 


e 


e gsk_secure_soc_write()--Send data on a secure session 


e gsk strerror()--Retrieve GSK runtime error message 
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gsk_secure_soc_misc()--Perform 
miscellaneous functions for a secure session 


Syntax 


#include <gskssl.h> 


int gsk_secure_soc_misc(gsk_handle my_session_handle, 
GSK_MISC_ID miscID); 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_secure_soc_misc() function is used to perform miscellaneous functions for a secure session. 


Parameters 


my_session_handle (Input) 


The handle for the secure session obtained from gsk_secure_soc_open() and after performing a 
gsk_secure_soc_init(). 


miscID (Input) 


One of the following operations: 


o GSK_RESET_CIPHER (100) - Performs another SSL handshake for the SSL session 
identified by the my_session_handle parameter. If an SSL session's cache entry is still valid 
and both end points of the SSL session allow using a cache entry, an abbreviated SSL 
handshake may be performed. If the SSL cache entry for this session has expired or if the 
SSL session's cache entry has been reset with the GSK_RESET_SESSION function, or if 
one end point of the SSL session does not allow using the SSL session cache entry, then a 
full SSL handshake will be performed. 


o GSK_RESET_SESSION (101) - Removes this set of SSL session attributes from the SSL 
session cache. Any new SSL session handshake requests to the peer end point will not use 
this set of attributes. In most cases, as result of this operation, a full SSL handshake will be 
performed for the next SSL handshake request between both end points. 


Authorities 


No authorization is required. 


Return Value 


gsk_secure_soc_misc() returns an integer. Possible values are: 
[GSK_OK] 


gsk_secure_soc_misc() was successful. 


[GSK_INVALID_HANDLE] 


The handle specified was not valid. 


[GSK_INVALID_STATE] 
A gsk_secure_soc_init() has not been issued with this handle. 


[GSK_ERROR_NOT_SSLV3] 
SSLV3 or TLSV1 is required for this function. 


[GSK_MISC_INVALID_ID] 


The value specified for miscID is not valid. 


[GSK_AS400_ERROR_INVALID_POINTER] 


The my_session_handle pointer is not valid. 


[GSK_INTERNAL_ERROR] 


An unexpected error occurred during SSL processing. 


[GSK_ERROR_IO] 


An error occurred in SSL processing; check the errno value. 


[GSK_KEYRING_OPEN_ERROR] 


Certificate store file could not be opened. 


[GSK_ERROR_BAD_KEYFILE_LABEL] 


The specified certificate store label is not valid. 


[GSK_ERROR_BAD_V3_CIPHER] 
An SSLV3 or TLSV1 cipher suite was specified that is not valid. 


[GSK_ERROR_BAD_V2_CIPHER] 
An SSLV2 cipher suite was specified that is not valid. 


[GSK_ERROR_NO_CIPHERS] 


No ciphers available or no ciphers were specified. 


[GSK_ERROR_NO_CERTIFICATE] 


No certificate is available for SSL processing. 


[GSK_ERROR_BAD_CERTIFICATE] 


The certificate is bad. 


[SSL_ERROR_NOT_TRUSTED_ROOT] 


The certificate is not signed by a trusted certificate authority. 


[GSK_KEYFILE_CERT_EXPIRED] 


The validity time period of the certificate has expired. 


[GSK_ERROR_BAD_MESSAGE] 


A badly formatted message was received. 


[GSK_ERROR_UNSUPPORTED] 
Operation is not supported by SSL. 


[GSK_ERROR_BAD_PEER] 


The peer system is not recognized. 


[GSK_ERROR_ CLOSED] 
The SSL session ended. 


[GSK_AS400_ERROR_NO_INITIALIZE] 


A successful gsk_environment_init() was not previously called with this handle. 


[GSK_AS400_ERROR_TIMED_OUT] 
The value specified for the handshake timeout expired before the handshake completed. 


[GSK_AS400_ERROR_NOT_TCP] 


The socket descriptor type is not SOCK_STREAM or the address family is not AF_INET#* or 
AF_INET6%. 


[GSK_AS400_ERROR_ALREADY_SECURE] 


The socket descriptor is already in use by another secure session. 


[GSK_INSUFFICIENT_STORAGE] 


Unable to allocate storage for the requested operation. 


Error Conditions 


When the gsk_secure_soc_misc() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[EINTR] 


Interrupted function call. 


[EDEADLK] 


Resource deadlock avoided. 


[ETERM] 


Operation terminated. 


[EIO] 


Input/output error. 


[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Usage Notes 


1. An SSL session's attributes that are negotiated as part of an SSL handshake may be cached by each 
end point involved in the SSL session and then reused as part of an abbreviated SSL handshake 
when allowed by both end points. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Related Information 


e gsk secure_soc_close()--Close a secure session 


e gsk_ secure_soc_init()--Negotiate a secure session 


e@ gsk secure_soc_open()--Get a handle for a secure session 


e gsk _strerror()--Retrieve GSK runtime error message 
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gsk_secure_soc_open()--Get a handle for a 
secure session 


Syntax 


#include <gskssl.h> 


int gsk_secure_soc_open(gsk_handle my_env_handle, 
gsk_handle *my_session_handle) ; 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_secure_soc_open() function is used to get storage for a secure session, set default values for 
attributes, and return a handle that must be saved and used on secure session-related function calls. 


Parameters 


my_env_handle (Input) 


The handle for the SSL environment obtained from gsk_environment_open(). 


my_session_handle (Output) 


Pointer to the secure session handle. 


Authorities 


No authorization is required. 


Return Value 


gsk_secure_soc_open() returns an integer. Possible values are: 
[GSK_OK] 


gsk_secure_soc_open() was successful. 


[GSK_INVALID_HANDLE] 


The environment handle specified was not valid. 


[GSK_INSUFFICIENT_STORAGE] 


Not able to allocate storage for the requested operation. 


[GSK_AS400_ERROR_INVALID_POINTER] 


The my_env_handle pointer is not valid. 


[GSK_INTERNAL_ERROR] 


An internal error occured during system processing. 


[GSK_ERROR_IO] 


An error occurred in SSL processing, check the errno value. 


Error Conditions 


When the gsk_secure_soc_open() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[EINTR] 


Interrupted function call. 


[EDEADLK] 


Resource deadlock avoided. 
[ETERM] 
Operation terminated. 


If an errno is returned that is not in this list, see Errno Values for UNIX-Type Functions for a description of 
the errno. 


Usage Notes 


1. After gsk_secure_soc_open() returns with a GSK_OK return value, attributes from the SSL 
environment will be used as the defaults for the subsequent gsk_secure_soc_init(). The defaults 
can be changed using the gsk_attribute_set_buffer(), gsk_attribute_set_enum(), or 
gsk_attribute_set_numeric_value() APIs after calling gsk_secure_soc_open() and before calling 
gsk_secure_soc_init(). 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Related Information 


e gsk attribute_set_bufferQ--Set character string information for a secure session or a SSL 
environment. 


e gsk_attribute_set_enum()--Set enumerated information for a secure session or a SSL environment. 


e gsk_ attribute_set_numeric_value()--Set numeric information for a secure session or a SSL 
environment 


e osk environment_open()--Get a handle for a SSL environment 


@ gsk_secure_soc_close()--Close a secure session 


e@ gsk_secure_soc_init()--Negotiate a secure session 


e@ gsk secure_soc_misc()--Perform miscellaneous functions for a secure session 


e@ gsk_strerror()--Retrieve GSK runtime error message 
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gsk_secure_soc_read()--Receive data ona 
secure session 


Syntax 


#include <gskssl.h> 


int gsk_secure_soc_read(gsk_handle my_session_handle, 
char *readBuffer, 
int readBufSize, 
int *amtRead); 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_secure_soc_read() function is used by a program to receive data from a secure session. 


Parameters 
my_session_handle (Input) 


The handle, returned from gsk_secure_soc_open() and used on the gsk_secure_soc_init() API call 
that initialized the secure session over which data is to be read. 


readBuffer (Output) 
The pointer to the user-supplied buffer in which the data is to be stored. 


readBufSize (Input) 
The number of bytes to be read. 


amtRead (Output) 


The number of bytes that were read as a result of this API call. 


Authorities 


No authorization is required. 


Return Value 


gsk_secure_soc_read() returns an integer. Possible values are: 
[GSK_OK] 


gsk_secure_soc_read() was successful. 


[GSK_INVALID_HANDLE] 


The handle specified was not valid. 


[GSK_INVALID_STATE] 


The handle is not in the correct state for this operation. 


[GSK_INVALID_BUFFER_SIZE] 
The readBufSize is less than 1. 


[GSK_WOULD_BLOCK] 


Operation would have caused the process to be suspended. 


[GSK_ERROR_BAD_MESSAGE] 


SSL received a badly formatted message. 


[GSK_ERROR_BAD_MAC] 


A bad message authentication code was received. 


[GSK_AS400_ERROR_CLOSED] 


The secure session was closed by another thread before the read completed. 


[GSK_AS400_ERROR_INVALID_POINTER] 


The readBuffer or amtRead pointer is not valid. 


[GSK_ERROR_SOCKET_CLOSED] 


A close() was done on the socket descriptor for this secure session. 


[GSK_INTERNAL_ERROR] 


An unexpected error occurred during SSL processing. 


[GSK_ERROR_IO] 


An error occurred in SSL processing; check the errno value. 


Error Conditions 


When the gsk_secure_soc_read() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[ECONNRESET] 


A connection with a remote socket was reset by that socket. 


[EIO] 


Input/output error. 


[ENOTCONN] 


Requested operation requires a connection. 
[EUNATCH] 
The protocol required to support the specified address family is not available at this time. 


Any errno that can be returned by recv() can be returned by this API. See Sockets APIs for a description of 
the errno values it can return. 


If an errno is returned that is not in this list, see Errno Values for UNIX-Type Functions for a description of 
the errno. 


Usage Notes 


1. The maximum length of data typically returned will not exceed 16 KB. This is because SSL is a 
record level protocol and the largest record allowed is 32 KB minus the necessary SSL record 
headers. 


2. It is strongly suggested that you do not mix the gsk_secure_soc_read() API with any of the sockets 
read functions. SSL and socket reads and writes can be mixed, but they must be performed in 
matched sets. If a client application writes 100 bytes of data using one or more of the socket send() 
calls, then the server application must read exactly 100 bytes of data using one or more of the 
socket recv() calls. This is also true for gsk_secure_soc_read() API. 


3. Since SSL is a record-oriented protocol, SSL must receive an entire record before it can be 
decrypted and any data returned to the application. Thus, a select() may indicate that data is 
available to be read, but a subsequent gsk_secure_soc_read() may hang waiting for the remainder 
of the SSL record to be received when using blocking I/O. 


4. A FIONREAD ioctl() cannot be used to determine the amount of data available for reading by 
using gsk_secure_soc_read(). 


5. SSL will ignore the out-of-band (OOB) data indicator. OOB will not affect the SSL application. 
OOB will just be data to the SSL protocol. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Related Information 


e gsk secure_soc_close()--Close a secure session 


e@ gsk secure_soc_init()--Negotiate a a secure session 


@ gsk secure_soc_misc()--Perform miscellaneous functions for a secure session 


e gsk secure_soc_open()--Get a handle for a secure session 


e@ gsk secure_soc_write()--Send data on a secure session 


e gesk_strerror()--Retrieve GSK runtime error message 
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»gsk_secure_soc _startlnit()--Start 
asynchronous operation to negotiate a secure 
session 


Syntax 


#include <gskssl.h> 
#include <qsoasync.h> 


int gsk_secure_soc_startInit (gsk_handle my_session_handle, 


int IOCompletionPort, 
Qso_OverlappedIO_t * communicationsArea) 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_secure_soc_startInit() function is used to initiate an asynchronous negotiation of a secure session, 
using the attributes set for the SSL environment and the secure session. This API starts the SSL handshake to 
the remote peer and upon successful completion of QsoWaitForIOCompletion() a secure session is 
established. 


Parameters 


my_session_handle (Input) 


The handle returned from gsk_secure_soc_open() that will be used to negotiate the secure session. 


int IOCompletionPort (Input) 
The I/O completion port that should be posted when the operation completes. 


Qso_OverlappedIO_t * communicationsArea (Input/Output) 


A pointer to a structure that contains the following information: 


descriptorHandle 


(Input) - The descriptor handle is application specific and is never used by the system. This 
field is intended to make it easier for the application to keep track of information regarding a 
given socket connection. 


buffer 
Not used. 
bufferLength 
Not used. 
postFlag 


Not used. 
postF lagResult 
Not used. 


fillBuffer 


Not used. 


returnValue 


(Output) - When the negotiate operation completes asynchronously, this field contains 
indication of success or failure. 


errno Value 


(Output) - When the negotiate operation completes asynchronously and returnValue is 
GSK_ERROR_IO, this field will contain an errno further defining the failure. 


operationCompleted 


(Output) - If the operation is posted to the I/O completion port, this field is updated to 
indicate that the operation was a GSKSECURESOCSTARTINIT. 


secureDataTransferSize 
Not used. 
bytesAvailable 

Not used. 
operation WaitTime 

Not used. 
postedDescriptor 


Not used - Must be set to zero. 
reserved] 

(Output) - Must be set to hexadecimal zeroes. 
reserved2 


(Input) - Must be set to hexadecimal zeroes. 


Authorities 


Authorization of *R (allow access to the object) to the certificate store file and its associated files is required. 
Authorization of *X (allow use of the object) to each directory of the path name of the certificate store file 
and its associated files is required. 


Return Values 


gsk_secure_soc_startInit() returns an integer. Possible values are: 


e GSK_OS400_ASYNCHRONOUS_SOC_INIT - The function has been started. When the function 
completes, the Qso_OverlappedIO_t communications structure will be updated with the results and 
the I/O completion port will be posted. 


e Ifthe function fails, possible values are: 


[GSK_INVALID_HANDLE] 

The handle specified was not valid. 
[GSK_OS400_ERROR_NO_INITIALIZE] 

A successful gsk_environment_init() was not previously called with this handle. 
[GSK_OS400_ERROR_NOT_TCP] 


The socket descriptor type is not SOCK_STREAM or the address family is not AF_INET#* 
or AF_INET6%&. 


[GSK_OS400_ERROR_ALREADY_SECURE] 

The socket descriptor is already in use by another secure session. 
[GSK_OS400_ERROR_INVALID_POINTER] 

The my_session_handle pointer is not valid. 
[GSK_INTERNAL_ERROR] 

An unexpected error occurred during SSL processing. 
[GSK_OS400_ERROR_INVALID_OVERLAPPEDIO_T] 

The Qso_OverLappedIO_t specified was not valid. 
[GSK_OS400_ERROR_INVALID_IOCOMPLETIONPORT] 

The I/O completion port specified was not valid. 
[GSK_OS400_ERROR_BAD_SOCKET_DESCRIPTOR] 

The socket descriptor specified within the gsk_handle was not valid. 
[GSK_ERROR_IO] 


An error occured in SSL processing; check the errno value. 


Error Conditions 


When gsk_secure_soc_startInit() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[EIO] 

Input/output error. 
[EUNATCH] 

The protocol required to support the specified address family is not available at this time. 


If an errno is returned that is not in this list, see Errno Values for UNIX-Type Functions for a description of 
the errno. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. The gsk_secure_soc_startInit() function is valid only on sockets that have an address family of 
AF_INET#* or AF_INET6*% and a socket type of SOCK_STREAM. 


2. The current implemention of the SSL Protocol does not allow gsk_secure_soc_startInit() to 
complete synchronously. Use gsk_secure_soc_init() if the synchronous behaviour is needed. 


Related Information 


e@ gsk_secure_soc_close()--Close a Secure Session 


e@ gsk secure_soc_init()--Negotiate a secure session 
e@ gsk secure_soc_misc()--Perform miscellaneous functions for a secure session 


@ gsk_secure_soc_open()--Get a handle for a secure session 


e@ gsk secure_soc_read()--Receive data on a secure session 


e gsk secure_soc_write()--Send data on a secure session 


e gsk secure_soc_startRecv--Start Asynchronous Recv Operation on a secure session 


e@ gsk_secure_soc_startSend--Start Asynchronous Send Operation on a secure session 


e@ QsoCreate[OCompletionPort()--Create I/O Completion Port 

e@ QsoDestroyIOCompletionPortQ)--Destroy I/O Completion Port 

e@ QsoPostlOCompletionPort()--Post Request on I/O Completion Port 
e@ QsoWaitForlOCompletion(--Wait for I/O Completion Operation 
e 
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gsk_secure_soc_startRecv()--Start asynchronous 
receive operation on a secure session 


Syntax 


#include <gskssl.h> 
#include <qsoasync.h> 


int gsk_secure_soc_startRecv (gsk_handle my_session_handle, 
int IOCompletionPort, 
Qso_OverlappedIO_t * communicationsArea) 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_secure_soc_startRecv() function is used to initiate an asynchronous receive operation on a secure session. 
The supplied receive buffer cannot be reused by the calling application until the receive is complete or the I/O 
completion port specified on the gsk_secure_soc_startRecv() has been destroyed. This API supports sockets with an 
address family of AF_INET 3 or AF_INET6% and type SOCK_STREAM only. 


Parameters 


my_session_handle (Input) 


The handle, returned from gsk_secure_soc_open() and used on the gsk_secure_soc_init() API call that 
initialized the secure session over which data is to be read. 


int [OCompletionPort (Input) 


The I/O completion port that should be posted when the operation completes. 


Qso_OverlappedIO_t * communicationsArea (Input/Output) 


A pointer to a structure that contains the following information: 


descriptorHandle 


(Input) - The descriptor handle is application specific and is never used by the system. This field is 
intended to make it easier for the application to keep track of information regarding a given socket 
connection. 


buffer 
(Input) - A pointer to a buffer into which data should be read. 
bufferLength 


(Input) - The length of the buffer into which data should be read. Also represents the amount of data 
requested. 


postFlag 


(Input) - The postFlag indicates if this operation should be posted to the I/O completion port even if it 
completes immediately. 


mu A 0 value indicates that if the operation is already complete upon return to the application, 


then do not post to the I/O completion port. 


m A | value indicates that even if the operation completes immediately upon return to the 
application, the result should still be posted to the I/O completion port. 


postFlagResult 


(Output) - This field is valid if gsk_secure_soc_startRecv() returns with | and postFlag was set to 1. 
In this scenario, postFlagResult set to 1 denotes the operation completed and been posted to the I/O 
completion port specified. A value of 0 denotes the operation could not be completed immediately, 

but will be handled asynchronously. 


fillBuffer 


(Input) - The fillBuffer flag indicates when this operation should complete. If the fillBuffer flag is 0, 
then the operation will complete as soon as any data is available to be received. If the fillBuffer flag 

is non-zero, this operation will not complete until enough data has been received to fill the buffer, an 
end-of-file condition occurs on the socket, or an error occurs on a socket. 


return Value 


(Output) - IF gsk_secure_soc_startRecv() completes synchronously (function return value equals 
GSK_OK), then this field is set to GSK_OK and field secure data transfer size indicates number of 
bytes received. 


errno Value 


(Output) - When the operation has completed asynchronously and returnValue is GSK_ERROR_IO, 
this field will contain an errno further defining the failure. 


operationCompleted 


(Output) - If the operation is posted to the I/O completion port, this field is updated to indicate that 
the operation was a GSKSECURESOCSTARTRECV. 


secureDataTrans ferSize 


(Output) - Number of bytes received when gsk_secure_soc_startRecv() completes synchronously 
(return value equals GSK_OK). 


a 
bytesAvailable 
Not used. 
operation WaitTime 
(Input) - A timeval structure which specifies the maximum time allowed for this operation to 
complete asynchronously. 
struct timeval { 
long tv_sec; /* second * / 
long tv_usec; /* microseconds * / 
}; 
If this timer expires, the operation will be posted to the I/O completion port with errnoValue set to 
EAGAIN. 
If this field is set to zero, the operation's asynchronous completion will not be timed. 
If socketDescriptor is closed before the operation completes or times out, the operation will be posted 
to the I/O completion port with errnoValue set to ECLOSED. 
The minimum operationWaitTime is | second. The microseconds field (tv_usec) in the timeval is not 
used and must be set to zero. 
postedDescriptor 


Not used - Must be set to zero. 


s 


reservedl 


(Output) - Must be set to hexadecimal zeroes. 
reserved2 


(Input) - Must be set to hexadecimal zeroes. 


Authorities 


No authorization is required. 


Return Values 


gsk_secure_soc_startRecv() returns an integer. Possible values are: 


e GSK_OK - The function has completed synchronously. The Qso_OverlappedIO_t communications structure 
has been updated but nothing has nor will be posted to the I/O completion port for this operation. Inspect field 
secureDataTransferSize in the Qso_OverlappedIO_t communications structure to determine the number of 
bytes received. 


e GSK_AS400_ASYNCHRONOUS_RECV - The function has been started. When the function completes = 
(or times out if operationWaitTime was specified), * the Qso_OverlappedIO_t communications structure 
will be updated with the results and the I/O completion port will be posted. 


e If the function fails, possible values are: 


[GSK_INVALID_HANDLE] 

The handle specified was not valid. 
[GSK_INVALID_STATE] 

The handle is not in the correct state for this operation. 
[GSK_INVALID_BUFFER SIZE] 

The bufferLength field located in the Qso_OverLappedIO_t communications area is less than 1. 
[GSK_ERROR_BAD_MESSAGE] 

SSL received a badly formatted message. 
[GSK_ERROR_BAD_MAC] 

A bad message authentization code was received. 
[GSK_ AS400_ERROR_INVALID_POINTER] 

The buffer pointer located in Qso_OverLappedIO_t communications area is not valid. 
[GSK_ERROR_SOCKET_CLOSED] 

A close() was done on the socket descriptor for this secure session. 
[GSK_INTERNAL_ERROR] 

An unexpected error occurred during SSL processing. 
[GSK_AS400_ERROR_INVALID_OVERLAPPEDIO_T] 

The Qso_OverLappedIO_t specified was not valid. 
[GSK_AS400_ERROR_INVALID_ IOCOMPLETIONPORT] 

The I/O completion port specified was not valid. 
[GSK_AS400_ERROR_BAD_SOCKET_DESCRIPTOR] 

The socket descriptor specified within the gsk_handle was not valid. 
[GSK_ERROR_IO] 


An error occured in SSL processing; check the errno value. 


Error Conditions 


When gsk_secure_soc_startRecv() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[ECONNRESET] 

A connection with a remote socket was reset by that socket. 

2 
[EINVAL] 


The field operationWaitTime.tv_sec was negative or operationWaitTime.tv_usec was not zero or 
postedDescriptor was not zero. 


“s 
[EIO] 

Input/output error. 
[ENOTCONN] 

Requested operation requires a connection. 
[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


If an errno is returned that is not in this list, see Errno Values for UNIX-Type Functions for a description of the 
errno. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. A buffer that is given to gsk_secure_soc_startRecv() must not be used by the application again until either it 
is returned by QsoWaitForlIOCompletion() or is reclaimed by issuing a close() on the socket descriptor or 
issuing a QsoDestroyIOCompletionPort() on the I/O completion port. If a buffer is given to 
gsk_secure_soc_startRecv() to be filled, and it is later detected during gsk_secure_soc_startRecv() 
processing that the buffer has been freed, it may produce an unrecoverable condition on the socket for which 
the gsk_secure_soc_startRecv() was issued. If this occurs, an ECONNABORTED error value will be 
returned. 


2. It is not recommended to intermix gsk_secure_soc_startRecv() and blocking I/O (ie, recv() or 
gsk_secure_soc_read()) on the same socket. If this condition occurs, then pending asynchronous recv I/O will 
be serviced first before the blocking I/O. 


3. The maximum length of data typically returned will not exceed 16 KB. This is due to the fact that SSL is a 
record level protocol and the largest record allowed is 32 KB minus the necessary SSL record headers. 


4. Socket option SO.RCVLOWAT is not supported by this API. Semantics similar to SO._RCVLOWAT can be 


obtained using the fillBuffer field in the Qso_OverLappedIO_t structure. 


5. 2% Socket option SO_LRCVTIMEO is not supported by this API. Semantics similar to SOLRCVTIMEO can be 
obtained using the operationWaitTime field in the Qso_OverLappedIO_t structure. 


6. It is strongly suggested that you do not mix the gsk_secure_soc_read() nor gsk_secure_soc_startRecv() 
APIs with any of the sockets read functions. However, SSL and socket reads and writes can be mixed, but 
they must be performed in matched sets. If a client application writes 100 bytes of data using one or more of 
the socket send() calls, then the server application must read exactly 100 bytes of data using one or more of 
the socket recv() calls. This is also true for gsk_secure_soc_read() and gsk_secure_soc_startRecv() APIs. 


7. A FIONREAD ioctl() cannot be used to determine the amount of data available for reading by using 


gsk_secure_soc_startRecv(). 


8. SSL will ignore the out of band (OOB) data indicator. OOB will not affect the SSL application. OOB will 
only be data to the SSL protocol. 


Related Information 


e@ gsk_secure_soc_close()--Close a Secure Session 


e@ gsk_secure_soc_init(Q)--Negotiate a secure session 


e@ gsk secure _soc_misc()--Perform miscellaneous functions for a secure session 


e@ gsk_secure_soc_open()--Get a handle for a secure session 


eo 


e@ gsk_secure_soc_startInit()--Start asynchronous operation to negotiate a secure session 


e 


e@ gsk_secure_soc_startSend()--Start Asynchronous Send Operation on a Secure Session 


e@ gsk_ secure_soc_write()--Send data on a secure session 


e@ QsoCreateIOCompletionPort()--Create I/O Completion Port 


e@ QsoDestroyl[OCompletionPort()--Destroy I/O Completion Port 


e@ QsoPostIOCompletionPort()--Post Request on I/O Completion Port 


e@ QsoStartRecv--Start Asynchronous Recv Operation 


e@ QsoStartSend--Start Asynchronous Send Operation 


@ QsoWaitForIOCompletion(--Wait for I/O Completion Operation 


e recv()--Receive Data 
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gsk_secure_soc_startSend()--Start 
asynchronous send operation on a secure 
session 


Syntax 


#include <gskssl.h> 
#include <qsoasync.h> 


int gsk_secure_soc_startSend (gsk_handle my_session_handle, 


int IOCompletionPort, 
Qso_OverlappedIO_t * communicationsArea) 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_secure_soc_startSend() function is used to initiate an asynchronous send operation on a secure 
session. The supplied send buffer cannot be reused by the calling application until the send is complete or the 
I/O completion port specified on the gsk_secure_soc_startSend() has been destroyed. This API supports 
sockets with an address family of AF_INET 2% or AF_INET6* and type SOCK_STREAM only. 


Parameters 


my_session_handle (Input) 


The handle, returned from gsk_secure_soc_open() and used on the gsk_secure_soc_init() API call that 
initialized the secure session over which data is to be written. 


int IOCompletionPort (Input) 
The I/O completion port that should be posted when the operation completes. 


Qso_OverlappedIO_t * communicationsArea (Input/Output) 


A pointer to a structure that contains the following information: 


descriptorHandle 


(Input) - The descriptor handle is application-specific and is never used by the system. This 
field is intended to make it easier for the application to keep track of information regarding a 
given socket connection. 


buffer 


(Input) - A pointer to a buffer of data that should be sent over the socket. 


bufferLength 


(Input) - The length of the data to be sent. 


postFlag 


(Input) - The postFlag indicates if this operation should be posted to the I/O completion port 
even if it completes immediately. 


a A value of 0 indicates that if the operation is already complete upon return to the 
application, then do not post to the I/O completion port. 


m A value of | indicates that even if the operation completes immediately upon return to 
the application, the result should still be posted to the I/O completion port. 


postFlagResult 


(Output) - This field is valid if gsk_secure_soc_startSend() returns with 1 and postFlag was set 
to 1. In this scenario, postFlagResult set to 1 denotes the operation completed and been posted 
to the I/O completion port specified. A value of 0 denotes the operation could not be completed 
immediately, but will be handled asynchronously. 


fillBuffer 


(Input) - Only used on gsk_secure_soc_startRecv() or QsoStartRecv(). Ignored on 
gsk_secure_soc_startSend(). 


returnValue 


(Output) - If gsk_secure_soc_startSend() completes synchronously (return value equals 
GSK_OK), then this field is set to GSK_OK and field secureDataTransferSize indicates 
number of bytes sent. 


errno Value 


(Output) - When the operation has completed asynchronously and returnValue is 
GSK_ERROR_IO, this field will contain an errno further defining the failure. 


operationCompleted 


(Output) - If the operation is posted to the I/O completion port, this field is updated to indicate 
that the operation was a GSKSECURESOCSTARTSEND. 


secureDataTransferSize 


(Ouput) - Number of bytes sent when gsk_secure_soc_startSend() completes synchronously 
(function return value equals GSK_OK). 


ea 
bytesAvailable 


Not used. 
operation WaitTime 


(Input) - A timeval structure which specifies the maximum time allowed for this operation to 
complete asynchronously. 


struct timeval { 
long tv_sec; /* second */ 
long tv_usec; /* microseconds */ 


by 
If this timer expires, the operation will be posted to the I/O completion port with errnoValue set 


to EAGAIN. 
If this field is set to zero, the operation's asynchronous completion will not be timed. 


If socketDescriptor is closed before the operation completes or times out, the operation will be 
posted to the I/O completion port with errnoValue set to ECLOSED. 


The minimum operationWaitTime is 1 second. The microseconds field (tv_usec) in the timeval 
is not used and must be set to zero. 
postedDescriptor 


Not used - Must be set to zero. 


“3 


reservedl 


(Input) - Must be set to hex zeroes. 


reserved2 


(Input) - Must be set to hex zeroes. 


Authorities 


No authorization is required. 


Return Values 


gsk_secure_soc_startSend() returns an integer. Possible values are: 


e GSK_OK- The function has completed synchronously. The Qso_OverlappedIO_t communications 
structure has been updated but nothing has nor will be posted to the I/O completion port for this 
operation. Inspect field secureDataTransferSize in the Qso_OverlappedIO_t communications structure 
to determine the number of bytes sent. 


e GSK_AS400_ASYNCHRONOUS_SEND - The function has been started. When the function 
completes #* (or times out if operationWaitTime was specified), “& the Qso_OverlappedIO_t 
communications structure will be updated with the results and the I/O completion port will be posted. 


e If the function fails, possible values are: 


[GSK_INVALID_HANDLE] 


The handle specified was not valid. 


[GSK_INVALID_STATE] 


The handle is not in the correct state for this operation. 
[GSK_INVALID_BUFFER SIZE] 
The bufferLength field located in the Qso_OverLappedIO_t communications area is less than 


1. 


[GSK_ERROR_SOCKET_CLOSED] 


A close() was done on the socket descriptor for this secure session. 


[GSK_ AS400_ERROR_INVALID_POINTER] 


The buffer pointer located in Qso_OverlappedIO_t communications area is not valid. 


[GSK_INTERNAL_ERROR] 


An unexpected error occurred during SSL processing. 


[GSK_AS400_ERROR_INVALID_OVERLAPPEDIO_T] 
The Qso_OverLappedIO_t specified was not valid. 


[GSK_AS400_ERROR_INVALID_ IOCOMPLETIONPORT] 


The I/O completion port specified was not valid. 


[GSK_AS400_ERROR_BAD_SOCKET_DESCRIPTOR] 
The socket descriptor specified within the gsk_handle was not valid. 


GSK_ERROR_IO] 
An error occured in SSL processing; check the errno value. 


Error Conditions 


When gsk_secure_soc_startSend() API fails with return code [GSK_ERROR_IO], errno can be set to: 


a 
[EINVAL] 


The field operationWaitTime.tv_sec was negative or operationWaitTime.tv_usec was not zero or 
postedDescriptor was not zero. 


ss 
[EIO] 


Input/output error. 


[ENOTCONN] 


Requested operation requires a connection. 


[ENOTSOCK] 


The specified descriptor does not reference a socket. 


[EPIPE] 
Broken pipe. 


[EUNATCH] 
The protocol required to support the specified address family is not available at this time. 


If an errno is returned that is not in this list, see Errno Values for UNIX-Type Functions for a description of the 


errno. 


Error Messages 


Message ID Error Message Text 


CPE3418 E Possible APAR condition or hardware failure. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. 


Since gsk_secure_soc_startSend() is asynchronous, care should be used to control how many of these 
functions are outstanding. When a TCP socket becomes flow control blocked such that the 
gsk_secure_soc_startSend() is not able to pass the data to the TCP socket immediately, the return 
value will be GSK_AS400_ASYNCHRONOUS_SEND. Applications that send large amounts of data 
should have the postFlag set to 0. This allows the application to use a return value of 
GSK_AS400_ASYNCHRONOUS_SEND as an indication that the socket has become flow control 
blocked. The application should then wait for the outstanding operation to complete before issuing 
another gsk_secure_soc_startSend(). This will ensure that the application does not exhaust system 
buffer resources. 


. A buffer that is given to gsk_secure_soc_startSend() must not be used by the application again until 


either it is returned by QsoWaitForlOCompletion() or is reclaimed by issuing a close() on the socket 
descriptor or issuing a QsoDestroy[OCompletionPort() on the I/O completion port. If a buffer is given 
to gsk_secure_soc_startSend() to be sent, and it is later detected during gsk_secure_soc_startSend() 
processing that the buffer has been freed, it may produce an unrecoverable condition on the socket for 
which the gsk_secure_soc_startSend() was issued. If this occurs, ana ECONNABORTED error value 
will be returned. 


. There is no maximum length of data that can be written. 


. It is not recommended to intermix gsk_secure_soc_startSend() and blocking I/O (ie, sendQ) or 


gsk_secure_soc_send()) on the same socket. If one does, then pending asynchronous send I/O will be 
serviced before blocking I/O once data can be sent. 


. Itis strongly suggested that you do not mix the gsk_secure_soc_write() nor 


gsk_secure_soc_startSend() APIs with any of the sockets write functions. However, SSL and socket 
reads and writes can be mixed, but they must be performed in matched sets. If a client application 
writes 100 bytes of data using one or more of the socket send() calls, then the server application must 
read exactly 100 bytes of data using one or more of the socket recv() calls. This is also true for 
gsk_secure_soc_write() and gsk_secure_soc_startSend()APIs. 


. 2* Socket option SO_SNDTIMEO is not supported by this API. Semantics similar to SO_SNDTIMEO 


can be obtained using the operationWaitTime field in the Qso_OverLappedIO_t structure. 


s 


Related Information 


e@ gsk_secure_soc_init()--Negotiate a secure session 


e@ gsk_secure_soc_misc()--Perform miscellaneous functions for a secure session 


@ gsk_ secure_soc_open()--Get a handle for a secure session 


@ gsk secure_soc_read()--Receive data on a secure session 


ex 


e esk secure_soc_startInit()--Start asynchronous operation to negotiate a secure session 


e <= 


@ gsk_secure_soc_startRecv()--Start Asynchronous Receive Operation on a Secure Session 


@ QsoPostIOCompletionPort()--Post Request on I/O Completion Port 


@ QsoCreatel[OCompletionPort()--Create I/O Completion Port 


@ QsoDestroyl[OCompletionPort()--Destroy I/O Completion Port 


@ QsoStartRecyv--Start Asynchronous Recv Operation 


@ QsoStartSend--Start Asynchronous Send Operation 
@ QsoWaitForlOCompletionQ--Wait for I/O Completion Operation 


e@ send()--Send Data 
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gsk_secure_soc_write()--Send data on a secure 
session 


Syntax 


#include <gskssl.h> 


int gsk_secure_soc_write(gsk_handle my_session_handle, 
char *writeBuffer, 
int writeBufSize, 
int *amtWritten); 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_secure_soc_write() function is used by a program to write data on a secure session. 


Parameters 
my_session_handle (Input) 
The handle, returned from gsk_secure_soc_open() and used on the gsk_secure_soc_init() API call 


that initialized the secure session over which data is to be written. 


writeBuffer (Input) 


The pointer to the user-supplied buffer from which the data is to be written. 


writeBufSize (Input) 


The number of bytes to be written. 


amtWritten (Output) 


The number of bytes written as a result of this API call. 


Authorities 


No authorization is required. 


Return Value 


gsk_secure_soc_write() returns an integer. Possible values are: 
[GSK_OK] 


gsk_secure_soc_write() was successful. 


[GSK_INVALID_HANDLE] 


The handle specified was not valid. 


[GSK_INVALID_STATE] 


The handle is not in the correct state for this operation. 


[GSK_INVALID_BUFFER_SIZE] 
The readBufSize is less than 1. 


[GSK_WOULD_BLOCK] 


Operation would have caused the process to be suspended. 


[GSK_ERROR_SOCKET_CLOSED] 


A close() was done on the socket descriptor for this secure session. 


[GSK_AS400_ERROR_CLOSED] 


The secure session was closed by another thread before the write completed. 


[GSK_AS400_ERROR_INVALID_POINTER] 


The writeBuffer or amtWritten pointer is not valid. 


[GSK_INTERNAL_ERROR] 


An unexpected error occurred during SSL processing. 


[GSK_ERROR_IO] 


An error occurred in SSL processing; check the errno value. 


Error Conditions 


When the gsk_secure_soc_write() API fails with return code [GSK_ERROR_IO], errno can be set to: 
[EIO] 


Input/output error. 


[ENOTCONN] 


Requested operation requires a connection. 


[ENOTSOCK] 


The specified descriptor does not reference a socket. 


[EPIPE] 
Broken pipe. 


[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


Any errno that can be returned by send() can be returned by this API. See Sockets APIs for a description of 
the errno values it can return. 


Usage Notes 


1. There is no maximum length of the data that can be written. 


2. It is strongly suggested that you do not mix the gsk_secure_soc_write() API with any of the 
sockets write functions. SSL and socket reads and writes can be mixed, but they must be performed 
in matched sets. If a client application writes 100 bytes of data using one or more of the socket 
send() calls, then the server application must read exactly 100 bytes of data using one or more of 
the socket recv() calls. This is also true for gsk_secure_soc_write() API. 


3. The amtWritten value is set to zero when return value is not GSK_OK. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Related Information 


e@ gsk secure_soc_init()--Negotiate a secure session 


@ gsk secure_soc_misc()--Perform miscellaneous functions for a secure session 


e@ gsk secure_soc_open()--Get a handle for a secure session 


e gsk_ secure_soc_read()--Receive data on a secure session 


e gsk _strerror()--Retrieve GSK runtime error message 
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gsk_strerror()--Retrieve GSKit runtime error 
message 


Syntax 


#include <gskssl.h> 


const char *gsk_strerror(int gsk_return_value) ; 


Service Program Name: QS YS/QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The gsk_strerror() function is used to retrieve an error message and associated text string that describes a 
return value that was returned from calling a GSKit API. 


Parameters 


gsk_return_value (Input) 
The return value received from a GSKit API. 


Authorities 


No authorization is required. 


Return Value 


gsk_strerror() returns a pointer to the return value text. 


Usage Notes 


1. gsk_strerror() returns a pointer to the string. The null-terminated string is stored in the CCSID of 
the job. 


2. If a gsk_return_value is specified for which there is no corresponding description, an Unknown 
Error string is returned. 


Related Information 


e gsk _attribute_get_bufferQ--Get character information about a secure session or an SSL 


environment. 


e gsk attribute_get_cert_info()--Get information about a local or partner certificate. 


e gsk attribute_get_enum()--Get enumerated information about a secure session or an SSL 
environment. 


e gsk attribute_get_numeric_value()--Get numeric information about a secure session or an SSL 
environment. 


e gsk attribute_set_buffer(--Set character information for a secure session or an SSL environment. 


e gsk_ attribute_set_enum()--Set enumerated information for a secure session or an SSL environment. 


e gsk_ attribute_set_numeric_value()--Set numeric information for a secure session or an SSL 


environment 


e gsk_ environment_close()--Close the SSL environment 


e gsk environment_init()--Initialize a SSL environment 


e gsk environment_open()--Get a handle for an SSL environment 


e gsk_ secure_soc_close()--Close a secure session 


e@ gsk secure_soc_init()--Negotiate a secure session 


e@ gsk_ secure_soc_misc()--Perform miscellaneous functions for a secure session 


e@ gsk secure_soc_open()--Get a handle for a secure session 


e@ gsk secure_soc_read()--Receive data on a secure session 


e@ gsk secure_soc_write()--Send data on a secure session 


Example 
The following example shows how gsk_strerror() is used: 


#include <stdio.h> 
#include <sys/types.h> 


#include <gskssl.h> 


void main() 
{ 
int rc = GSK_OK; 
gsk_handle env_handle = NULL; 


re = gsk_environment_open(&env_handle) ; 
if (rc != GSK_OK) 
{ 
printf ("gsk_environment_open() failed with re = %d %$s\n", 


rc,gsk_strerror(rc)); 
break; 


} 
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OS/400 Secure Sockets Layer (SSL_) APIs 


OS/400 SSL_ APIs, when used in addition to the existing OS/400 Sockets APIs, provide the functions 
required for applications to establish secure communications. An application using SSL for secure 
communications is basically a client/server application written using sockets. 


The SSL_ APIs are: 


e OlgSSL Init(Q (Initialize the current job for SSL (using NLS-enabled path name)) is used to 
establish the SSL security information to be used for all SSL sessions for the current job. 


e SSL_Create() (Enable SSL support for the specified socket descriptor) is used by a program to 
enable SSL support for the specified socket descriptor. 


e SSL _Destroy(Q (End SSL support for the specified SSL session) is used by a program to end SSL 
support for the specified SSL session. 


e SSL_Handshake() (Initiate the SSL handshake protocol) is used by a program to initiate the SSL 


handshake protocol. Both the client and the server program must call the SSL_Handshake verb in 
order to initiate the handshake processing. 


e SSL InitQ initialize the current job for SSL) is used to establish the SSL security information to 
be used for all SSL sessions for the current job. 


e SSL Init ApplicationQ (Establish the SSL security information) is used to establish the SSL 


security information to be used for all SSL sessions for the current job based on the specified 
application identifier. 


e SSL PerrorQ (Print SSL error message) prints an error message to stderr. 


e SSL_ReadQ (Receive data from an SSL-enabled socket descriptor) is used by a program to receive 
data from an SSL-enabled socket descriptor. 

e SSL_StrerrorQ (Retrieve SSL runtime error message) is used to retrieve an error message and 
associated text string which describes an SSL return value. 


e SSL _WriteQ (Write data to an SSL-enabled socket descriptor) is used by a program to write data to 
an SSL-enabled socket descriptor. 


Note: These functions use header (include) files from the library QS YSINC, which is optionally installable. 
Make sure QSYSINC is installed on your system before using any of the functions. See Header Files for 


UNIX-Type Functions for the file and member name of each header file. 


See the following examples for more information: 


e Example: Establish secure server with SSL APIs 
e Example: Establish secure client with SSL APIs 
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QIgSSL_Init()--Initialize the Current Job for SSL 
(using NLS-enabled path name) 


Syntax 


#include <ssl.h> 


int QlgSSL_Init (QlgSSLInit* init) 


Service Program Name: *SRVPGM 
Default Public Authority: *USE 
Threadsafe: Yes 


The QlgSSL_Init() function is used to establish the SSL security information to be used for all SSL sessions for the 
current job. The QlgSSL_Init() API establishes a certificate and private key for use by the handshake protocol 
processing when acting as a server. The Ql/gSSL_Init() API establishes a certificate for use by the handshake 
protocol processing when acting as a client that is connected to a server performing client authentication. 


Parameters 
QigSSLInit * init (input) 


The pointer to a QlgSSLInit structure. QlgSSLInit is a typedef for a buffer of type struct OlgSSLInitS¢r. In 
<ssl.h>, struct QlgSSLInitStr is defined as the following: 


struct QlgSSLInitStr { /* QlgSSLInitStr 


Qlg_Path_Name* keyringFileName; /* Key ring file name 


char* keyringPassword; /* Key ring file password 

unsigned short int* cipherSuiteList; /* List of cipher suites 

unsigned int cipherSuiteListLen; /* number of entries in 
the cipher suites list 


The fields within the QlgSSLInit structure as pointed to by init are defined as follows: 
Qlg_Path_Name_T *keyringFileName (input) 


A pointer to a structure defining the path to the key ring file. This structure defines the coded 
character set identifier (CCSID) and the path to the key ring file to be used for this job's SSL 
processing. The path must be a fully qualified integrated file system file name. 


char *keyringPassword (input) 
A pointer to the password for the key ring file named in the keyring FileName field. 


If this parameter's value is equal to NULL, then the Q/gSSL_Init() support will attempt to extract a 
password from a key-ring password file. 


This parameter is assumed to be represented in the same CCSID (coded character set identifier) as 
the keyringFileName. 


unsigned short int* cipherSuiteList (input) 


A pointer to the cipher specification list to be used during the SSL handshake protocol for this job. 
This list is a string of concatenated cipher specification values. A cipher specification value is an 
unsigned short integer. Any value provided will override any values provided by a previous 
QlgSSL_Init() API or the system default cipher specification list if the previous Q/gSSL_Init() API 
did not provide a cipher specification list. A value of NULL for this parameter indicates one of the 
following: 


m Use the cipher specification list provided by a previous Q/gSSL_Init() API 
m Use the system default cipher specification list if a previous QlgSSL_Init() API was not 
done 


The caller specifies the preferred order of the cipher specifications. The cipher specification values 
are defined in ssl.h as the following: 


SSL_RSA_WITH_NULL_MD5 O0x0001 
SSL_RSA_WITH_NULL_SHA 0x0002 
SSL_RSA_EXPORT_WITH_RC4_40_MD5 0x0003 
SSL_RSA_WITH_RC4_128_MD5 0x0004 
SSL_RSA_WITH_RC4_128_SHA 0x0005 


SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 0x0006 
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA 0x0008 


SSL_RSA_WITH_DES_CBC_SHA 0x0009 
SSL_RSA_WITH_3DES_EDE_CBC_SHA OxO000A 
SSL_RSA_WITH_RC2_CBC_128_MD5 OxFFO1 
SSL_RSA_WITH_DES_CBC_MD5 OxFFO2 
SSL_RSA_WITH_3DES_EDE_CBC_MD5 OxFFO3 


Notes: 
1. The SSL_RSA_EXPORT_WITH_DES40_CBC_SHA cipher is not supported by OS/400. 


2. The list of cipher specifications will be different between the Cryptographic Access 
Provider 40-Bit (5769AC1), Cryptographic Access Provider 56-Bit (5769AC2), 
Cryptographic Access Provider 128-Bit (5769AC3) licensed products. If one of the 
cryptographic products is installed and an application attempts to use a cipher specification 
that is not allowed only for that cryptographic product, they will receive an EINVAL errno. 


3. The default cipher suite list for the Internet Connection Secure Server (US) 5769AC3 
product in preference order is as follows: 


SSL_RSA_WITH_RC4_128_SHA 
SSL_RSA_WITH_RC4_128_MD5 
SSL_RSA_WITH_DES_CBC_SHA 
SSL_RSA_WITH_DES_CBC_MD5 
SSL_RSA_WITH_3DES_EDE_CBC_SHA 
SSL_RSA_WITH_3DES_EDE_CBC_MD5 
SSL_RSA_WITH_RC2_CBC_128_MD5 
SSL_RSA_EXPORT_WITH_RC4_40_MD5 
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 


4. The default cipher suite list for the Internet Connection Secure Server (US) 5769AC2 
product in preference order is as follows: 


SSL_RSA_WITH_DES_CBC_SHA 
SSL_RSA_WITH_DES_CBC_MD5 
SSL_RSA_EXPORT_WITH_RC4_40_MD5 


SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 


5. The default cipher suite list for the Internet Connection Secure Server (International) 
5769AC1 product in preference order is as follows: 


SSL_RSA_EXPORT_WITH_RC4_40_MD5 
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 


unsigned int cipherSuiteListLen (input) 


The number of cipher suite entries specified in the list pointed to by the cipherSuiteList parameter. 


Authorities 


Authorization of *R (allow access to the object) to the key ring file and its associated files is required. 


Return Value 


The QlgSSL_Init() API returns an integer. Possible values are: 
[0] 

Successful return 
[SSL_ERROR_BAD_CIPHER_SUITE] 

A cipher suite that is not valid was specified. 
[SSL_ERROR_IO] 

An error occurred in SSL processing; check the errno value. 
[SSL_ERROR_KEYPASSWORD_EXPIRED] 

The specified key ring password has expired. 
[SSL_ERROR_NO_KEYRING] 

No key ring file was specified. 
[SSL_ERROR_SSL_NOT_AVAILABLE] 

SSL is not available for use. 
[SSL_ERROR_UNKNOWN] 


An unknown or unexpected error occurred during SSL processing. 


Error Conditions 


When the QigSSL_Init() API fails with return code [SSL_ERROR_IO], errno can be set to: 
[EINVAL] 


Parameter not valid. 


This error code indicates that the Qlg_Path_Name_T structure was not valid: 
oO. The path type was less than 0 or greater than 3. 


o Areserved field was not initialized to zeros. 


[ECONVERT] 


Conversion error. 


This error code indicates one of the following: 


oO The CCSID specified in the keyringFileName cannot be converted to the current default CCSID 
for integrated file system path names. 


oO There was an incomplete character or shift state sequence at the end of the keyringFileName path 
or keyringPassword. 


[EACCES] 


Permission denied. 


This error code indicates one of the following: 
oO The keyringFileName field contains a file name to which the user is not authorized. 


oO The keyringPassword value is not valid for the specified keyringFileName. 


[EBADF] 


Descriptor not valid. 


This error code indicates one of the following: 


oO The keyring FileName value does not specify a valid key ring file name. 


[EFAULT] 
Bad address. 
The system detected an address that was not valid while attempting to access the init parameter or one of 
the address fields in the init parameter. 

[EUNATCH] 


The protocol required to support the specified address family is not available at this time. 


[EUNKNOWN] 


Unknown system state. 


Error Messages 


CPE3418 E 

Possible APAR condition or hardware failure. 
CPF9872 E 

Program or service program &1 in library &2 ended. Reason code &3. 
CPFAOS] E 


Unable to set return value or error code. 


Usage Notes 


1. A successful SSL_Init(), QlgSSL_Init (using NLS-enabled path name), or SSL_Init_Application() API must 
be used to enable a job for SSL processing before attempting to use any other SSL API. 


2. If multiple SSL_Init_Application(), QlgSSL_Init (using NLS-enabled path name), or SSL_Init() APIs are 
performed in a job, then only the values associated with the last SSL_Init_Application(), QlgSSL_Init (using 
NLS-enabled path name), or SSL_Init() performed are used. 


3. If the keyringPassword parameter pointer value is equal to NULL, then QlgSSL_Init will attempt to extract 
the password value from the key-ring password file associated with the keyringFileName parameter's value. 
The existence of the associated key-ring password file is based on a configuration selection made during the 
creation of the key ring file. 


Related Information 


e@ SSL_Create()--Enable SSL Support for the Specified Socket Descriptor 
e@ SSL_DestroyQ--End SSL Support for the Specified SSL Session 


e SSL_Handshake()--Initiate the SSL Handshake Protocol 


e SSL _Init()--Initialize the Current Job for SSL 


e SSL Init Application(--Initialize the Current Job for SSL Processing Based on the Application Identifier 


e SSL _Read()--Receive Data from an SSL-Enabled SocketDescriptor 


e SSL_WriteQ--Write Data to an SSL-Enabled Socket Descriptor 
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SSL_Create()--Enable SSL Support for the 
Specified Socket Descriptor 


Syntax 


#include <ssl.h> 


SSLHandle* SSL_Create(int socket_descriptor, 
int flags) 


Service Program Name: QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The SSZ_Create() function is used by a program to enable SSL support for the specified socket descriptor. 


Parameters 


int socket_descriptor (input) 


The descriptor of the socket to be used for the SSL session. The socket descriptor must have been 
created (using the socket() API) with a type of SOCK_STREAM and an address family of 
AF_INET#* or AF_INET6*&. 


int flags (input) 
A flag value that controls the use of SSL for the session. The flags value is either zero, or is 
obtained by the ORing of the following constant: 


SSL_ENCRYPT (1< <0) 
Encrypt the connection. 
SSL_DONT_ENCRYPT (0) 


Do not encrypt the connection. 


Authorities 


No authorization is required. 


Return Value 


The SSL_Create() API returns a pointer to an SSLHandle. A value of NULL is returned when 
SSL_Create() fails. An SSLHandle is a typedef for a buffer of type struct SSLHandleStr. In <ssl.h>, struct 
SSLHandleStr is defined as the following: 


struct SSLHandleStr { /* SSLHandleStr * / 

int fd; /* Socket descriptor */ 
int createFlags; /* SSL_Create flags value * / 
unsigned protocol; /* SSL protocol version e7 
unsigned timeout; /* Timeout value in seconds */ 
unsigned char cipherKind[3]; /* Current 2.0 cipher suite*/ 
unsigned short int cipherSuite; /* Current 3.0 cipher suite ey 
unsigned short int* cipherSuiteList; /* List of cipher suites */ 
unsigned int cipherSuiteListLen; /* Number of entries in 

the cipher suites list Ay 
unsigned char* peerCert; /* Peer certificate * / 
unsigned peerCertLen; /* Peer certificate length aA 
int peerCertValidateRc; /* Return code from 

validation of certficate sa 
int (*exitPgm) (struct SSLHandleStr* sslh); 


/* Authentication exit 
program called when a 
certificate is received 
during SSL handshake */ 
}; 


Note: A full explanation of each of the members of the above structure are defined in the SSL_Handshake() 
API description. 


The SSLHandle structure returned will be initialized to hexadecimal zeros with the exception of the fd 


field, which will be initialized to the socket_descriptor input parameter and the createFlags field, which 
will be initialized to the flags input parameter. 


Error Conditions 


When the SSL_Create() API fails, errno can be set to: 


[EALREADY] Operation already in progress. 


[EBADF] Descriptor not valid. 
[EFAULT] Bad address. 
[EINVAL] Parameter not valid. 


This error code indicates one of the following: 


e The socket_descriptor type is not SOCK_STREAM or address family is not 
AF_INET # or AF_INET6*S. 


e@ One of the parameters passed is not valid or is NULL. 
[EIO] Input/output error. 


[ENOBUFS] There is not enough buffer space for the requested operation. 


[ENOTSOCK] _ The specified descriptor does not reference a socket. 
[EPIPE] Broken pipe. 


[EUNATCH] The protocol required to support the specified address family is not available at this 
time. 


[EUNKNOWN]_ Unknown system state. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFAO081 E Unable to set return value or error code. 


Usage Notes 


1. The SSL_Create() function is only valid on sockets that have an address family of AF_INET#* or 
AF_INET6* and a socket type of SOCK_STREAM. If the descriptor pointed to by the 
socket_descriptor parameter does not have the correct address family and socket type, 
[SSL_ERROR_IO] is returned and the errno value is set to EINVAL. 


2. If the flags parameter specifies a value that does not include the SSL_ENCRYPT flag, then the SSL 
protocol will not be used for the connection. Not using the SSL protocol has the following effects: 


o The SSL_Handshake() API will simply return successful without performing any function. 


o The SSL_Read() API will simply call the sockets read() API with the same set of input 
parameters. 


o The SSL_Write() API will simply call the sockets write() API with the same set of input 
parameters. 


3. Any use of givedescriptor() and takedescriptor() APIs must be performed prior to issuing an 
SSL_Create(). 


Related Information 


e SSL _ Destroy()--End SSL Support for the Specified SSL Session 


e SSL_Handshake()--Initiate the SSL Handshake Protocol 


SSL_Init()--Initialize the Current Job for SSL 


SSL_Read(Q)--Receive Data from an SSL-Enabled Socket Descriptor 


e SSL WriteQ--Write Data to an SSL-Enabled Socket Descriptor 
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SSL_Destroy()--End SSL Support for the Specified 
SSL Session 


Syntax 


#include <ssl.h> 


int SSL_Destroy(SSLHandle* handle) 


Service Program Name: QSOSSLSR 


Default Public Authority: *USE 


Threadsafe: Yes 


The SSL_Destroy() function is used by a program to end SSL support for the specified SSL session. The SSL 


session to be ended is identified by the handle parameter. 


Parameters 


SSLHandle* handle (input) 


The pointer to an SSLHandle for an active SSL session, which is being ended. An SSLHandle is a 
typedef for a buffer of type struct SSLHandleStr. In <ssl.h>, struct SSLHandleStr is defined as the 


following: 

struct SSLHandleStr { /* SSLHandleStr 
int fd; /* Socket descriptor 
int createFlags; /* SSL_Create flags value 
unsigned protocol; /* SSL protocol version 
unsigned timeout; /* Timeout value in seconds 
unsigned char cipherKind[3]; /* Current 2.0 cipher suite*/ 
unsigned short int cipherSuite; /* Current 3.0 cipher suite 


he 


unsigned short 
unsigned int 


unsigned char* 
unsigned 


int 


int 


int* cipherSuiteList; /* List of cipher suites 
cipherSuiteListLen; /* Number of entries in 
the cipher suites list 
peerCert; /* Peer certificate 
peerCertLen; /* Peer certificate length 
peerCertValidateRc; /* Return code from 


val 
(*exitPgm) (struct SSLHandl 


lidation of certficate 
leStr* sslh); 


/* Authentication exit 
program called when a 
certificate is received 
during SSL handshake 


Si. 
a: 
% 
*ef 
*f 


ef 
if 
* 
* 
*/ 


*/ 


mai 


Authorities 


No authorization is required. 


Return Value 


The SSL_Destroy() API returns an integer. Possible values are: 
[0] Successful return 


[SSL_ERROR_IO] An etror occurred in SSL processing; check the errno value. 


Error Conditions 


When the SSL_Destroy() API fails with return code [SSL_ERROR_IO], errno can be set to: 


[EBADF] Descriptor not valid. 


[EFAULT] Bad address. 


The system detected an address that was not valid while attempting to access the handle 
parameter or a field within the structure pointed to by the handle parameter. 


[EIO] Input/output error. 


[EINVAL] Parameter not valid. This error code indicates one of the following: 


e The socket_descriptor type is not SOCK_STREAM or address family is not 
AF_INET # or AF_INET6%. 


e@ One of the parameters passed is not valid or is NULL. 


[ENOTCONN] _ Requested operation requires a connection. 


This error code indicates that the socket_descriptor has not had SSL support enabled. This 
usually means that an SSL_Create() has not been completed for this socket_descriptor. 


[ENOTSOCK] _ The specified descriptor does not reference a socket. 
[EPIPE] Broken pipe. 


[ETIMEDOUT] A remote host did not respond within the timeout period. 


This error code indicates that the SSL_Destroy() was unable to successfully complete the 
removal of SSL support on this socket_descriptor. 


[EUNATCH] The protocol required to support the specified address family is not available at this time. 


[EUNKNOWN] Unknown system state. 


Error Messages 


Message ID 
CPE3418 E 
CPF9872 E 
CPFA081 E 


Error Message Text 
Possible APAR condition or hardware failure. 
Program or service program &1 in library &2 ended. Reason code &3. 


Unable to set return value or error code. 


Usage Notes 


1. All storage referenced from any field within the structure pointed to by the handle parameter and the 
storage pointed to by the handle parameter itself will be freed upon a successful return. 


2. Unpredictable results will occur if you attempt to use an SSL_Destroy() while sending or receiving data 
on the peer system. 


3. If an SSL_Destroy() is not done, then the storage referenced by the handle parameter will not be freed 
until the job ends. 


Note: A job end might cause a Licensed Internal Code log entry or error log entry if the handle parameter 
storage is not freed before the job ended. 


4. If an SSL_Destroy() is not done, the storage referenced by the handle parameter will not be freed. This 
will result in a memory leak. A memory leak is the loss of a piece of system memory because it is not 
allocated to any process on the system. 


Related Information 


e SSL_Create()--Enable SSL Support for the Specified Socket Descriptor 


e SSL_Handshake()--Initiate the SSL Handshake Protocol 


e SSL_Init()--Initialize the Current Job for SSL 


e SSL_ReadQ--Receive Data from an SSL-Enabled Socket Descriptor 


e SSL_WriteQ--Write Data to an SSL-Enabled Socket Descriptor 
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SSL_Handshake()--Initiate the SSL Handshake 
Protocol 


Syntax 


#include <ssl.h> 


int SSL_Handshake (SSLHandle* handle, 
int how) 


Service Program Name: QSOSSLSR 
Default Public Authority: *USE 


Threadsafe: Yes 


The SSL_Handshake() function is used by a program to initiate the SSL handshake protocol. Both the client and the server 
program must call the SSL_Handshake verb in order to initiate the handshake processing. 


Parameters 


SSLHandle* handle (input/output) 


The pointer to an SSLHandle for an SSL session. An SSLHandle is a typedef for a buffer of type struct 
SSLHandleStr. In <ssl.h>, struct SSLHandleStr is defined as the following: 


struct SSLHandleStr { /* SSLHandleStr 
x / 

int fd; /* Socket descriptor 
*/, 

int createFlags; /* SSL_Create flags value 
ah 

unsigned protocol; /* SSL protocol version 
*/ 

unsigned timeout; /* Timeout value in seconds 
*/ 

unsigned char cipherKind[3]; /* Current 2.0 cipher suite 
47; 

unsigned short int cipherSuite; /* Current 3.0 cipher suite 
* 

unsigned short int* cipherSuiteList; /* List of cipher suites 
ai 

unsigned int cipherSuiteListLen; /* Number of entries in 

the cipher suites list 

*/, 

unsigned char* peerCert; /* Peer certificate 
a 

unsigned peerCertLen; /* Peer certificate length 
*/ 

int peerCertValidateRc; /* Return code from 

validation of certficate 

af 

int (*exitPgm) (struct SSLHandleStr* sslh); 


/* Authentication exit 
program called when a 
certificate is received 


during SSL handshake 


The fields within the SSLHandle structure as pointed to by handle are defined as follows: 


int fd (input) The socket descriptor of the connection for which the SSL handshake protocol is to be 
performed. This field was initialized by a prior SSL_Create() API. 


int createFlags (input) Whether or not the SSL protocol is to be used. If the field specifies a value that does not 
include the SSL_ENCRYPT flag, then this function will return success without performing 
the SSL handshake protocol. This field was initialized by a prior SSL_Create() API. 


unsigned int protocol The type of SSL handshake protocol to be performed. The protocol(s) that are acceptable as 
(input/output) the handshake protocol for this job. The following values may be specified for protocol and 
are defined in ssI.h. 


SSL_VERSION_CURRENT 0 (TLS with SSL Version 3.0 and SSL 
Version 2.0 compatibility) 

SSL Version 2.0 only) 

SSL Version 3.0 only) 

TLS Version 1 only) 

TLS Version 1 with SSL 

Version 3.0 compatibility) 


SSL_VERSION_2 
SSL_VERSION_3 
TLS_VERSION_1 
TLSV1_SSLV3 


Ow WN 


( 
( 
( 
( 


Upon return, this field will be set to reflect the protocol version actually negotiated. If the 
createFlags field specifies a value that does not include the SSL_ENCRYPT flag, then this 
field will be unchanged from its input value. 


unsigned timeout (input) The approximate number of seconds to wait for the SSL handshake protocol to complete. A 
value of 0 indicates to wait forever for the handshake to complete. 


unsigned char The cipher kind (which is the SSL Version 2.0 cipher suite) negotiated by the handshake. 
cipherKind[3] (output) 


unsigned short int The cipher suite type negotiated by the handshake. 
cipherSuite (output) 


unsigned short int* A pointer to a cipher specification list that is to be used during the handshake negotiation for 

cipherSuiteList (input) this SSL session. This list is a string of concatenated cipher specification values. Each cipher 
specification is an unsigned short integer value. Any value provided will override, for this 
SSL session, the default cipher specification list provided by a previous SSL_Init() API or 
SSL_Init_Application() API . The valid cipher suites allowed are defined in ssh. A value 
of NULL indicates one of the following: 


e@ Use the cipher specification list provided by a previous SSL_Init() API or 
SSL_Init_Application() API 


e Use the system default cipher specification list if the previous SSL_Init() API or 
SSL_Init_Application() API did not provide a cipher specification list 


unsigned int The number of cipher suite entries specified in the list pointed to by the cipherSuiteList 
cipherSuiteListLen field. 
(input) 


unsigned char* peerCert The pointer to the certificate received from the peer system. For a client, this is a pointer to 

(output) the server's certificate. For a server with client authentication enabled, this is a pointer to the 
client's certificate. For a server without client authentication this pointer value remains 
unchanged. 


unsigned peerCertLen The length of the certificate pointed to by the peerCert field. 


(output) 
int A pointer to a user supplied function that is called whenever a certificate is received during 
(*exitPgm)(SSLHandle* handshake processing. The exitPgm will be passed the pointer to the handle, which could 
sslh) (input) include the peer's certificate. The exitPgm returns a nonzero value if the peer's certificate is 
accepted. The return of a zero value by the exitPgm will cause the handshake processing to 
fail. Users of this function do not need to provide an exit program. The pointer should be a 
NULL value if there is not a user-supplied exit program. The exit program should be written 
in a threadsafe manner. 
int how (input) The type of SSL handshake to be performed: 
O Perform the handshake as a client. 
ZI Perform the handshake as a server. 
2 Perform the handshake as a server with client authentication. 
3 Perform the handshake as a server with optional client authentication. 
Authorities 


Authorization of *R (allow access to the object) to the key ring file and its associated files is required. 


Return Value 


The SSL_Handshake() API returns an integer. Possible values are: 


Value Description 
[0] Successful return 
[SSL_ERROR_BAD_CERTIFICATE] The certificate is bad. 
[SSL_ERROR_BAD_CERT_SIG] The certificate's signature is not valid. 
[SSL_ERROR_BAD_CERTIFICATE] The certificate is bad. 
[SSL_ERROR_BAD_CIPHER_SUITE] A cipher suite that is not valid was specified. 
[SSL_ERROR_BAD_MAC] A bad message authentication code was received. 
[SSL_ERROR_BAD_MALLOC] Unable to allocate storage required for SSL processing. 
[SSL_ERROR_BAD_MESSAGE] SSL received a badly formatted message. 
[SSL_ERROR_BAD_PEER] The peer system is not recognized. 
[SSL_ERROR_BAD_STATE] SSL detected a bad state in the SSL session. 


[SSL_ERROR_CERTIFICATE_REJECTED ] The certificate is not valid or was rejected by the exit 
| program. 


| [SSL_ERROR_CERT_EXPIRED] The validity time period of the certificate is expired. 
| [SSL_ERROR_CLOSED] The SSL session ended. 


[SSL_ERROR_IO] An error occurred in SSL processing; check the errno 
| value. 


| [SSL_ERROR_NO_CERTIFICATE] No certificate is available for SSL processing. 
| [SSL_ERROR_NO_CIPHERS] No ciphers available or specified. 
| [SSL_ERROR_NO_INIT] SSL_Init() was not previously called for this job. 


| [SSL_ERROR_NOT_TRUSTED_ROOT] The certificate is not signed by a trusted certificate 
authority. 


| [SSL_ERROR_PERMISSION_DENIED] Permission was denied to access object. 
| [SSL_ERROR_SELF_SIGNED] The certificate is self-signed. 
| [SSL_ERROR_SSL_NOT_AVAILABLE] SSL is not available for use. 


[SSL_ERROR_UNKNOWN] An unknown or unexpected error occurred during SSL 
processing. 


| [SSL_ERROR_UNSUPPORTED_CERTIFICATE_TYPE] | OS/400 does not support the certificate's type. 
| [SSL_ERROR_UNSUPPORTED_CERTIFICATE_TYPE] | OS/400 does not support the certificate's type. 


Error Conditions 


When the SSL_Handshake() API fails with a return code of [SSL_ERROR_IO], errno can be set to: 


[EACCES] Permission denied. 
[EBADF] Descriptor not valid. 
[EBUSY] Resource busy. 


[EDEADLK] Resource deadlock avoided. 


[EFAULT] Bad address. 


The system detected an address that was not valid while attempting to access the handle parameter or 
one of the address fields in the handle parameter. 


[EINTR] Interrupted function call. 


[EINVAL] Parameter not valid. 


This error code indicates one of the following: 


e The socket_descriptor type is not SOCK_STREAM or address family is not AF_INET or 
AF_INET6&. 


e@ One of the parameters passed is not valid or is NULL. 


e The protocol field contains a value that is not valid. 


[EALREADY] Operation already in progress. 
An SSL_Handshake() API has already been previously successfully completed. 


[EIO] Input/output error. 
[ENOBUFS] There is not enough buffer space for the requested operation. 


[ENOTCONN] _ Requested operation requires a connection. 


This error code indicates one of the following: 
e The socket_descriptor is not for a socket that is in a connected state. 


e@ The socket_descriptor has not had SSL support enabled. 


[ENOTSOCK] _ The specified descriptor does not reference a socket. 

[EPIPE] Broken pipe. 

[ETIMEDOUT] A remote host did not respond within the timeout period. 

[EUNATCH] The protocol required to support the specified address family is not available at this time. 


[EUNKNOWN] — Unknown system state. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. The SSL_Handshake() function is only valid on sockets that have an address family of AF_INET > or AF_INET6 
€ and a socket type of SOCK_STREAM. If the descriptor pointed to by the handle structure parameter does not 
have the correct address family and socket type, [SSL_ERROR_IO] is returned and the errno value is set to 
EINVAL. 


2. The SSL_Handshake() function can be called only one time per SSL session. If a secondary call of 
SSL_Handshake() occurs within the same established SSL session, then it will fail and the errno will be set to 
[EINVAL]. 


3. A successful SSL_Init() or or SSL_Init_Application() API and a successful SSL_Create() API must be called prior 
to an SSL_Handshake() API. The SSL_Init() API or SSL_Init_Application() API is used to establish a certificate 
and private key for either of the following: 


o A successful handshake as a server 


o A successful handshake as a client when connected to a server performing client authentication 


4. The SSL_Create() API is used to enable SSL support for the specified socket descriptor. 


Related Information 


e SSL Create()--Enable SSL Support for the Specified Socket Descriptor 
e SSL_DestroyQ--End SSL Support for the Specified SSL Session 


e SSL _Init()--Initialize the Current Job for SSL 
e SSL_ReadQ--Receive Data from an SSL-Enabled Socket Descriptor 
e SSL_WriteQ--Write Data to an SSL-Enabled Socket Descriptor 


API introduced: V4R3 
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SSL_Init()--Initialize the Current Job for SSL 


Syntax 


#include <ssl.h> 


int SSL_Init(SSLInit* init) 


Service Program Name: QSOSSLSR 
Default Public Authority: *USE 


Threadsafe: Yes 


The SSL_Init() function is used to establish the SSL security information to be used for all SSL sessions for the 
current job. The SSL_Init() API establishes the certificate and the associated public and private key information for 
use by the SSL handshake protocol processing when acting as a server or when acting as a client. The certificate and 
key information is needed by an application that is acting as a client in the situations where the client is connecting to 


a server which has enabled and requires client authentication. 


Parameters 


SSLInit * init (input) 


The pointer to an SSLInit structure. SSLInit is a typedef for a buffer of type struct SSLInitS¢r. In <ssl.h>, 


struct SSLInitStr is defined as the following: 


struct SSLInitStr { /* 


char* keyringFileName; fe 
char* keyringPassword; ial 


unsigned short int* cipherSuiteList; /* 
unsigned int cipherSuiteListLen; 


SSLInitStr 


Key ring file name 

Key ring file password 
List of cipher suites 

/* number of entries in 
the cipher suites list 


The fields within the SSLInit structure as pointed to by init are defined as follows: 


char *keyringFileName (input) 


A pointer to a null-terminated character string, identifying the path to the key database file to be used for this 
job's SSL processing. The path must be a fully qualified integrated file system file name. 


This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect 
for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default 


CCSID of the job. 


#See QleSSL_Init()--Initialize the Current Job for SSL (using NLS-enabled path name) for a description of 


supplying the keyringFileName in any CCSID.*%& 


char *keyringPassword (input) 


A pointer to a null-terminated character string, identifying the password for the key database file named in the 


keyring FileName field. 


If this parameter's value is equal to NULL, then the SSZ_Jnit() support will attempt to extract the key 
database password that has been securely stored on the system. 


This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect 
for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default 
CCSID of the job. 


unsigned short int* cipherSuiteList (input) 


A pointer to the cipher specification list to be used during the SSL handshake protocol for this job. This list is 
a string of concatenated cipher specification values. A cipher specification value is an unsigned short integer. 
Any value provided will override any values provided by a previous SSL_Init() API or 
SSL_Init_Application() API or the system default cipher specification list if the previous SSL_Init() API or 
SSL_Init_Application() API did not provide a cipher specification list. A value of NULL for this parameter 
indicates one of the following: 


o Use the cipher specification list provided by a previous SSL_Init() API or SSL_Init_Application() API 
o Use the system default cipher specification list if a previous SSL_Init() API or SSL_Init_Application() 
API was not done 


The caller specifies the preferred order of the cipher specifications. The cipher specification values, shown 
here not in preferred or strength order, are defined in ssl.h as the following: 


TLS_RSA_WITH_NULL_MD5 O0x0001 
TLS_RSA_WITH_NULL_SHA 0x0002 
TLS_RSA_EXPORT_WITH_RC4_40_MD5 0x0003 
TLS_RSA_WITH_RC4_128_MD5 0x0004 
TLS_RSA_WITH_RC4_128_SHA 0x0005 
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 0x0006 
TLS_RSA_WITH_DES_CBC_SHA 0x0009 
TLS_RSA_WITH_3DES_EDE_CBC_SHA OxO000A 
TLS_RSA_WITH_AES_128_CBC_SHA Ox002F 
TLS_RSA_WITH_RC2_CBC_128_MD5 OxFFO1 
TLS_RSA_WITH_DES_CBC_MD5 OxFFO2 
TLS_RSA_WITH_3DES_EDE_CBC_MD5 OxFFO3 


Notes: 
1. The SSL_RSA_EXPORT_WITH_DES40_CBC_SHA cipher is not supported by OS/400. 


2. The list of cipher specifications will be different between the Cryptographic Access Provider 56-Bit 
(5722AC2), Cryptographic Access Provider 128-Bit (5722AC3) licensed products. If one of the 
cryptographic products is installed and an application attempts to use a cipher specification that is not 
allowed only for that cryptographic product, they will receive an EINVAL errno. 


3. The default cipher suite list for the Internet Connection Secure Server (US) 5722AC3 product in 
preference order is as follows: 


TLS_RSA_WITH_RC4_128_MD5 
TLS_RSA_WITH_RC4_128_SHA 
TLS_RSA_WITH_3DES_EDE_CBC_SHA 
TLS_RSA_WITH_DES_CBC_SHA 
TLS_RSA_EXPORT_WITH_RC4_40_MD5 
LS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 
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4. The default cipher suite list for the Internet Connection Secure Server (US) 5722AC2 product in 


preference order is as follows: 
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LS_RSA_WITH_DES_CBC_SHA 
LS_RSA_EXPORT_WITH_RC4_40_MD5 
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 
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unsigned int cipherSuiteListLen (input) 


The number of cipher suite entries specified in the list pointed to by the cipherSuiteList parameter. 


Authorities 


Authorization of *R (allow access to the object) to the key database file and its associated files is required. 


Return Value 


The SSL_IJnit() API returns an integer. Possible values are: 


Value Description 
[0] Successful return 
[SSL_LERROR_BAD_CIPHER_SUITE] A cipher suite that is not valid was specified. 
[SSL_ERROR_IO] An error occurred in SSL processing; check the errno value. 
[SSL_ERROR_KEYPASSWORD_EXPIRED] | The specified key ring password has expired. 
[SSL_ERROR_NO_KEYRING] No key ring file was specified. 
[SSL_LERROR_SSL_NOT_AVAILABLE] SSL is not available for use. 
[SSL_ERROR_UNKNOWN] An unknown or unexpected error occurred during SSL processing. 


Error Conditions 


When the SSL_Init() API fails with return code [SSL_ERROR_IO], errno can be set to: 
[EINVAL] Parameter not valid. 
[EACCES] Permission denied. 


This error code indicates one of the following: 
e The keyringFileName field contains a file name to which the user is not authorized. 


e The keyringPassword value is not valid for the specified keyring FileName. 
[EBADF] Descriptor not valid. 


This error code indicates one of the following: 


e The keyringFileName value does not specify a valid key ring file name. 


[EFAULT] 


[EUNATCH] 


Bad address. 


The system detected an address that was not valid while attempting to access the init parameter 
or one of the address fields in the init parameter. 


The protocol required to support the specified address family is not available at this time. 


[EUNKNOWN] Unknown system state. 


Error Messages 


Message ID 
CPE3418 E 
CPF9872 E 
CPFA081 E 


Error Message Text 
Possible APAR condition or hardware failure. 
Program or service program &1 in library &2 ended. Reason code &3. 


Unable to set return value or error code. 


Usage Notes 


1. BA successful SSL_Init(), OlgSSL_Init (using NLS-enabled path name), or an SSL_Init_Application() API 
must be used to enable a job for SSL processing before attempting to use any other SSL API. 


2. If multiple SSL_Init_Application (), QlgSSL_Init, or SSL_Init() APIs are performed in a job, then only the 
values associated with the last SSL_Init_Application(), QlgSSL_Init, or or SSL_Init() performed are used.*& 


3. If the keyringPassword parameter pointer value is equal to NULL, then SSL_Init() will attempt to extract the 
password value as stored on the system with the keyringFileName parameter's value. The existence of the 
securely stored key database password is based on a configuration selection made during the creation of the 
key database file. 


Related Information 


e@ #QlgSSL_Init()--Initialize the Current Job for SSL (using NLS-enabled path name)** 


e SSL Create()--Enable SSL Support for the Specified Socket Descriptor 


e SSL _Destroy()--End SSL Support for the Specified SSL Session 
e SSL_Handshake()--Initiate the SSL Handshake Protocol 


e@ 2SSL_Init_Application()--Initialize the Current Job for SSL Processing Based on the Application Identifier 


Ls 


e SSL _Read()--Receive Data from an SSL-Enabled Socket Descriptor 


e SSL _WriteQ--Write Data to an SSL-Enabled Socket Descriptor 


API introduced: V4R3 
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SSL_Init_Application()--Initialize the Current Job for 
SSL Processing Based on the Application Identifier 


Syntax 


#include <ssl.h> 


int SSL_Init_Application (SSLInitApp* 
init_app) 


Service Program Name: QSOSSLSR 
Default Public Authority: *USE 


Threadsafe: Yes 


The SSL_Init_Application() function is used to establish the SSL security information to be used for all SSL sessions for 
the current job based on the specified application identifier. The SSL_Init_Application() API uses the application 
identifier to determine and then establish the certificate and the associated public and private key information for use by 
the SSL handshake protocol processing when acting as a server or when acting as a client. The certificate and key 
information is needed by an application that is acting as a client in the situaitons where the client is connecting to a server 
which has enabled and requires client authentication. 


Parameters 


SSLInitApp * init_app (input) 


The pointer to an SSLInitApp value. SSLInitApp is a typedef for a buffer of type struct SSLInitAppStr. In 
<ssl.h>, struct SSLInitAppStr is defined as the following: 


struct SSLInitAppStr { SSLInitAppStr 

char* applicationID; application id value 
unsigned int applicationIDLen; length of application id 
char* localCertificate; local certificate 
unsigned int localCertificateLen; ength of local certificate 
unsigned short int* cipherSuiteList; List of cipher suites 
unsigned int cipherSuiteListLen; number of entries in 

the cipher suites list 


unsigned int sessionType; the type of application as 
registered 

unsigned int reservedl; reserved - must be 0 

unsigned int protocol; SSL protocol version 

unsigned int timeout; cache timeout (seconds) 

char reserved[12]; reserved — must be NULL (0s) 


The fields within the SSLInitApp structure as pointed to by init_app are defined as follows: 
char *applicationID (input) 


A pointer to a null terminated character string identifying the application identifier value that was used to register 


the application using the Register Application for Certificate Use, (OPM, QS YRGAP; ILE, 
QsyRegisterAppForCertUse) API. See the Register Application for Certificate Use API for information on the 
format and values allowed for the application identifier. 


char *applicationIDLen (input) 


The number of characters in the application identifier string as specified by the applicationID parameter. 


char *localCertificate (input) 


On input, the localCertificate pointer must be set to point to storage that has been allocated by the calling 
application that will be used on output to contain the application's registered local certificate. If a certificate is not 
to be returned then set this pointer's value to NULL and the localCertificateLen value to zero (0). The storage 
should be large enough to accomodate the size of the certificate. Most certificates are less than 2K in length. On 
output, the localCertificate pointer will not be changed, though the storage it points to will contain the registered 
application's certificate. The certificate will be the one registered for that application by the Register Application 
for Certificate Use (OPM, QSYRGAP; ILE, QsyRegisterAppForCertUse) API. See the Register Application for 
Certificate Use API for information on the format and values allowed for the application identifier. 


unsigned intlocalCertificateLen (input) 


On input, this value must equal the number of characters available in the storage pointed to by the 
localCertificate pointer. Set this value to 0 if you do not want a certificate returned by this API. On output, this 
value is equal to the length of the certificate. If the certificate will not fit into the storage provided, then this value 
will be set to the length required to contain the certificate. 


» unsigned short int* cipherSuiteList (input) 


A pointer to the cipher specification list to be used during the SSL handshake protocol for this job. This list is a 
string of concatenated cipher specification values. A cipher specification value is an unsigned short integer. Any 
value provided will override any values provided by a previous SSL_Init_Application() API or SSL_Init() API or 
the system default cipher specification list if the previous SSL_Init_Application() API or SSL_Init() API did not 
provide a cipher specification list. A value of NULL for this parameter indicates one of the following: 


o Use the cipher specification list provided by a previous SSL_Init_Application() API or SSL_Init() API 
o Use the system default cipher specification list if a previous SSL_Init_Application() API or SSL_Init() 
API was not done 


The caller specifies the preferred order of the cipher specifications. The cipher specification values, shown here 
not in preferred or strength order, are defined in ssl.h as the following: 


TLS_RSA_WITH_NULL_MD5 0x0001 
TLS_RSA_WITH_NULL_SHA 0x0002 
TLS_RSA_EXPORT_WITH_RC4_40_MD5 0x0003 
TLS_RSA_WITH_RC4_128_MD5 0x0004 
TLS_RSA_WITH_RC4_128_SHA 0x0005 
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 0x0006 
TLS_RSA_WITH_DES_CBC_SHA 0x0009 
TLS_RSA_WITH_3DES_EDE_CBC_SHA Ox000A 
TLS_RSA_WITH_AES_128_CBC_SHA 0x002F 
TLS_RSA_WITH_RC2_CBC_128_MD5 OxFFO1 
TLS_RSA_WITH_DES_CBC_MD5 OxFFO2 


TLS_RSA_WITH_3DES_EDE_CBC_MD5 OxFFO3 


Notes: 
1. The SSL_RSA_EXPORT_WITH_DES40_CBC_SHA cipher is not supported by OS/400. 


2. The list of cipher specifications will be different between the Cryptographic Access Provider 56-Bit 
(5722AC2), Cryptographic Access Provider 128-Bit (5722AC3) licensed products. If one of the 
cryptographic products is installed and an application attempts to use a cipher specification that is not 
allowed only for that cryptographic product, they will receive an EINVAL errno. 


3. The default cipher suite list for the Internet Connection Secure Server (US) 5722AC3 product in 
preference order is as follows: 


TLS_RSA_WITH_RC4_128_MD5 
TLS_RSA_WITH_RC4_128_SHA 
TLS_RSA_WITH_3DES_EDE_CBC_SHA 
TLS_RSA_WITH_DES_CBC_SHA 
TLS_RSA_EXPORT_WITH_RC4_40_MD5 
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 


4. The default cipher suite list for the Internet Connection Secure Server (US) 5722AC2 product in 
preference order is as follows: 


TLS_RSA_WITH_DES_CBC_SHA 
TLS_RSA_EXPORT_WITH_RC4_40_MD5 
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 
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unsigned int cipherSuiteListLen (input) 


The number of cipher suite entries specified in the list pointed to by the cipherSuiteList parameter. 


unsigned int sessionType (output) 


The type registered for the application. The following values are returned in sessionType and are defined in ssl.h. 


SSL_REGISTERED_AS_CLIENT 0 
SSL_REGISTERED_AS_SERVER i 
SSL_REGISTERED_AS_SERVER_WITH_CLIENT_AUTH 2 
SSL_REGISTERED_AS_SERVER_WITH_OPTIONAL_CLIENT_AUTH 3 
SSL_REGISTERED_AS_NOT_SPECIFIED 99 


unsigned int reserved] (input) 


This reserved field must be set to 0. 


unsigned int protocol (input) 


The protocol(s) that are acceptable as the handshake protocol for this job. The following values may be specified 
for protocol and are defined in ssl.h. 


SSL_VERSION_CURRENT 0 (TLS with SSL Version 3.0 and SSL 
Version 2.0 compatibility) 


SSL_VERSION_2 
SSL_VERSION_3 
TLS_VERSION_1 
TLSV1_SSLV3 


SSL Version 2.0 only) 
SSL Version 3.0 only) 
TLS Version 1 only) 
TLS Version 1 with SSL 
Version 3.0 compatibility) 
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unsigned int timeout (input) 


The time period (in seconds) for which TLS Version 1.0 and SSL Version 3.0 session parameters are cached for 
use with abbreviated SSL handshakes. The valid range for timeout is from | to 86,400 seconds (24 hours). Not 
specifying a value (0) will default to the maximum timeout, and specifying a value of Oxffffffff will disable 
caching. The following values are defined in ss|.h. 


SSL_TIMEOUT_DEFAULT 0 (Use default timeout, 24 hours) 

SSL_TIMEOUT_MAX 86400 (Use maximum timeout, 24 hours) 

SSL_TIMEOUT_DISABLE Oxffffffff (Disable caching of session parameters 
for abbreviated handshakes) 


char reserved[12] (input) 
This reserved field must be set to NULL (0s). 


Authorities 


Authorization of *R (allow access to the object) to the key database file and its associated files is required. The certificate 
is stored in a key database file. 


Return Value 


The SSL_Init_Application() API returns an integer. Possible values are: 


| Value | Description 

[0] | Successful return 

| [SSL_ERROR_BAD_CIPHER_SUITE] | A cipher suite that is not valid was specified. 

| [SSL_ERROR_CERT_EXPIRED] | The validity time period of the certificate is expired. 
| [SSL_ERROR_KEYPASSWORD_EXPIRED] | The specified key ring password has expired. 


[SSL_ERROR_NOT_REGISTERED] The application identifier is not registered with the certificate registry 
| facility. 


| [SSL_ERROR_NOT_TRUSTED_ROOT] | The certificate is not signed by a trusted certificate authority. 
| [SSL_ERROR_NO_CERTIFICATE] | No certificate is available for SSL processing. 
| [SSL_ERROR_IO] | An error occurred in SSL processing; check the errno value. 


| [SSL_ERROR_SSL_NOT_AVAILABLE] | SSL is not available for use. 
| [SSL_ERROR_UNKNOWN] | An unknown or unexpected error occurred during SSL processing. 


Error Conditions 


When the SSL_Init_Application() API fails with return code [SSL_ERROR_IO], errno can be set to: 


[EINVAL] 
[EACCES] 


[EFAULT] 


[EUNATCH] 


Parameter not valid. 
Permission denied. 


This error code indicates one of the following: 


e The applicationID field contains a registered application identifier to which the user is not 
authorized. 


e@ The user profile, which the application is operating under, is not authorized to the key 
database file or its associated files. 


Bad address. 


The system detected an address that was not valid while attempting to access the init_app parameter 
or one of the address fields in the init_app parameter. 


The protocol required to support the specified address family is not available at this time. 


[EUNKNOWN] Unknown system state. 


Error Messages 


Message ID 
CPE3418 E 
CPF9872 E 
CPFA081 E 


Error Message Text 
Possible APAR condition or hardware failure. 
Program or service program &1 in library &2 ended. Reason code &3. 


Unable to set return value or error code. 


Usage Notes 


1. Before the SSL_Init_Application() API can be used, the user must have registered the application using the 
Register Application for Certificate Use (OPM, QSYRGAP; ILE, QsyRegisterAppForCertUse) API. The 
Register Application For Certificate Use API registers an application with the registry facility, allowing an 
application to be associated with a specific certificate. The Register Application for Certificate Use is described 
in the System Programming Interface Reference. If the applicaiton is not registered with the registry facility, then 
an error of SSL_ERROR_NOT_REGISTERED will be returned by SSL_Init_Application(). 


2. A successful SSL_Init(), >SSL_Init (using NLS-enabled path name),* or an SSL_Init_Application() API must be 
used to enable a job for SSL processing before attempting to use any other SSL API. 


3. If multiple SSL_Init_Application(), >SSL_Init (using NLS-enabled path name), or multiple SSL_Init() APIs are 
performed in a job, then only the values associated with the last SSL_Init_Application(), > SSL_Init (using 
NLS-enabled path name ),*& or SSL_Init() performed are used. 


4. If the SSL_Init_Application() API or SSL_Init() API are both performed in the same job, then only the values 
associated with the last API performed are used. 


5. The reserved fields in the SSLInitApp structure must be set to NULLs (Os) before using this API. 


Related Information 


e > YigSSL_Init()--Initialize the Current Job for SSL (using NLS-enabled path name) 


e SSL Create()--Enable SSL Support for the Specified Socket Descriptor 


A 


e SSL _Destroy(Q--End SSL Support for the Specified SSL Session 


e SSL InitQ--Initialize the Current Job for SSL 
SSL_Handshake()--Initiate the SSL Handshake Protocol 


SSL_Read(Q)--Receive Data from an SSL-Enabled Socket Descriptor 


e SSL_WriteQ--Write Data to an SSL-Enabled Socket Descriptor 


API introduced: V4R4 


Top | UNIX-Type APIs | APIs by category 


SSL_Perror()--Print SSL Error Message 


Syntax 


#include <ssl.h> 

void SSL_Perror(int sslreturnvalue, 
const char* string); 

Service Program Name: QSOSSLSR 

Default Public Authority: *USE 

Threadsafe: Yes 


The SSZ_Perror() function prints an error message to stderr. If string is not NULL and does not point to a 
null character, the string pointed to by string is printed to the standard error stream. If a string is printed, it 
is followed by a colon and a space. Regardless of if string was printed or not, the message associated with 
the sslreturnvalue is printed followed by a new-line character. Also, the message associated with the 
thread's errno is printed followed by a new-line character. 


Parameters 


int sslreturnvalue (Input) 
The Return Value received from a SSL API. 


char* string (Input) 


The string to be printed prior to the message associated with the ss/returnvalue. If no preceding 
message is desired, NULL must be entered. 


Authorities 


No authorization is required. 


Return Value 


There is no return value. 


Error Conditions 


This API calls the Retrieve SSL Runtime Error Message (SSL_Strerror) API in order to perform its task. It 
inherits all error conditions from this function. If the sslreturnvalue is unrecognized or if unable to retrieve 
the message corresponding to sslreturnvalue, then an Unknown error message will be printed following 
the string. Also, the message associated with the value found in the thread's errno is printed. Note: the 
value of errno may be updated by SSL_Perror() in some error conditions. 


Error Messages 


See Error Conditions. 


Related Information 


e SSL _ StrerrorQ--Retrieve SSL Runtime Error Message 


e SSL Create()--Enable SSL Support for the Specified Socket Descriptor 
e SSL _ DestroyQ--End SSL Support for the Specified SSL Session 

e@ SSL_Handshake()--Initiate the SSL Handshake Protocol 

e SSL_Init()--Initialize the Current Job for SSL 


e SSL Init Application(Q--Initialize the Current Job for SSL Processing Based on the Application 
Identifier 


e SSL _ Read()--Receive Data from an SSL-Enabled Socket Descriptor 
e SSL_WriteQ--Write Data to an SSL-Enabled Socket Descriptor 


Example 


The following example shows how SSL_Perror() is used: 


#include <stdio.h> 
#include <sys/types.h> 
#include <sys/socket.h> 
#include <ssl.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 
#include <errno.h> 


/* bufferLen is 250 bytes */ 
#define bufferLen 250 


void main () 

{ 
int bufferLen, on = 1, re = 0, sd, sd2, addrlen = 0; 
char buffer[bufferLen]; 


SSLInit sslinit; 
SSLHandle* sslh; 


struct sockaddr_in addr; 


unsigned short int cipher[3] = { 
SSL_RSA_WITH_RC4_128_MD5, 
SSL_RSA_WITH_RC4_128_SHA, 
SSL_RSA_EXPORT_WITH_RC4_40_MD5 
}; 


[RK KKK KR RK KK KK KKK KK KK KK KK KK KK / 


/* memset sslinit structure to hex zeros and Be/ 
/* £111 in values for the sslinit structure * / 


[RK KKK KR RK KK KK KK KK RK EK KK KK KK KKK / 


memset ((char *)&SSL_Init, 0x00, sizeof(sslinit)); 
sslinit.keyringFileName "/keyringfile.kyr"; 
sslinit.keyringPassword = NULL; 
sslinit.cipherSuiteList = &cipher[0]; 
sslinit.cipherSuiteListLen = 3; 


[RK KKK KKK KK KK KK KK KK KK KK KK / 


/* initialize SSL security call SSL_Init * / 
[RK KKK KKK KK KK KK RK KK RK KK KK KK KK / 
if ((re = SSL_Init (ésslinit)) != 0) 


{ 


SSL_Perror(rc, "Could not initialize SSL"); 


} 


} 
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SSL_Read()--Receive Data from an SSL-Enabled 
Socket Descriptor 


Syntax 


#include <ssl.h> 


int SSL_Read(SSLHandle *handle, 
void *buffer, 
int buffer_length) 


Service Program Name: QSOSSLSR 
Default Public Authority: *USE 


Threadsafe: Yes 


The SSLZ_Read() function is used by a program to receive data from an SSL-enabled socket descriptor. 


Parameters 


SSLHandle* handle (input) 


The pointer to an SSLHandle for an SSL session. An SSLHandle is a typedef for a buffer of type struct 
SSLHandleStr. In <ssl.h>, struct SSLHandleStr is defined as the following: 


t SSLHandleStr { /* SSLHandleStr 

int fd; /* Socket descriptor 

int createFlags; /* SSL_Create flags value 

unsigned protocol; /* SSL protocol version 

unsigned timeout; /* Timeout value in seconds 
unsigned cipherKind[3]; /* Current 2.0 cipher suite*/ 
unsigned int cipherSuite; /* Current 3.0 cipher suite 
unsigned int* cipherSuiteList; /* List of cipher suites 
unsigned cipherSuiteListLen; /* Number of entries in 

the cipher suites list 
unsigned peerCert; /* Peer certificate 

unsigned peerCertLen; /* Peer certificate length 

int peerCertValidateRc; /* Return code from 

validation of certficate 
int (*exitPgm) (struct SSLHandleStr* sslh); 

/* Authentication exit 
program called when a 
certificate is received 
during SSL handshake 


void *buffer (input) 


A pointer to the user-supplied buffer in which the data that is received on the SSL session is to be stored. 


int buffer_length (input) 
The length of the buffer. 


Authorities 


No authorization is required. 


Return Value 


The SSL_Read() API returns an integer. Possible values are: 


| Value | Description 

[n] Successful, where n is the number of bytes read. 
| [SSL_ERROR_BAD_MESSAGE] SSL received a badly formatted message. 

| [SSL_ERROR_BAD_MAC] A bad message authentication code was received. 


[SSL_ERROR_BAD_MALLOC] Unable to allocate storage required for SSL 
processing. 


| [SSL_ERROR_BAD_STATE] SSL detected a bad state in the SSL session. 
| [SSL_ERROR_CLOSED] The SSL session ended. 


[SSL_ERROR_IO] An error occurred in SSL processing; check the errno 
| value. 


| [SSL_ERROR_PERMISSION_DENIED ] Permission was denied to access object. 


[SSL_ERROR_UNKNOWN] An unknown or unexpected error occurred during 
SSL processing. 


| [SSL_ERROR_UNSUPPORTED_CERTIFICATE_TYPE] | OS/400 does not support the certificate's type. 


tt 


Error Conditions 


When the SSL_Read() API fails with return code [SSL_ERROR_IO], errno can be set to: 
[EBADF] Descriptor not valid. 
[ECONNRESET] A connection with a remote socket was reset by that socket. 


[EFAULT] Bad address. 


One of the following conditions occurred: 


e The system detected an address that was not valid while attempting to access the 
buffer parameter. 


e The system detected an address that was not valid while attempting to access the 
handle parameter or one of the address fields in the handle parameter. 


[EINVAL] Parameter not valid. 


This error code indicates one of the following: 


e The socket_descriptor type is not SOCK_STREAM or address family is not 
AF_INET 3 or AF_INET6%. 


e@ One of the parameters passed is not valid or is NULL. 


e@ The buffer_length parameter specifies a negative value. 


[EIO] Input/output error. 


[ENOTCONN] Requested operation requires a connection. 


This error code indicates one of the following: 
e The socket_descriptor is not for a socket that is in a connected state. 


e The socket_descriptor has not had SSL support enabled. This usually means that an 
SSL_Create() has not been completed for this socket_descriptor. 


[ENOTSOCK] The specified descriptor does not reference a socket. 

[ETIMEDOUT] A remote host did not respond within the timeout period. 

[EUNATCH] The protocol required to support the specified address family is not available at this time. 
[EUNKNOWN] Unknown system state. 


[EWOULDBLOCK]_ Operation would have caused the thread to be suspended. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. The SSL_Read() function is only valid on sockets that have an address family of AF_INET = or AF_INET6 
« and a socket type of SOCK_STREAM. If the descriptor pointed to by the handle structure parameter does 
not have the correct address family and socket type, [SSL_ERROR_IO] is returned and the errno value is set 
to EINVAL. 


2. The maximum length of data returned will not exceed 32 KB. This is due to the fact that SSL is a record level 
protocol and the largest record allowed is 32 KB minus the necessary SSL record headers. 


3. If the createFlags field in the SSLHandle specifies a value that does not include the SSL_LENCRYPT flag, 
this function will simply call the sockets read() function. 


4. Unpredictable results will occur when attempting to mix invocations to SSL_Read() and any of the sockets 
read functions (recv(), read(), readv(), and so forth). It is strongly suggested that you do not mix the 
SSL_Read() API with any of the sockets read functions. 


5. Since SSL is a record-oriented protocol, SSL must receive an entire record before it can be decrypted and any 
data returned to the application. Thus, a se/ect() may indicate that data is available to be read, but a 
subsequent SSL_Read() may hang waiting for the remainder of the SSL record to be received when using 
blocking I/O. 


6. A FIONREAD ioct#l() cannot be used to determine the amount of data available for reading by using 
SSL_Read(). 


7. SSL will ignore the out of band (OOB) data indicator. OOB will not affect the SSL application. OOB will 
just be data to the SSL protocol. 


8. For an SSL enabled socket, which must use a connection-oriented transport service (that is, TCP), a returned 
value of zero indicates one of the following: 


o. The partner program has issued a close() for the socket. 
o. The partner program has issued a shutdown() to disable writing to the socket. 
o The connection is broken and the error was returned on a previously issued socket function. 


o A shutdown() to disable reading was previously done on the socket. 


9. If an SSL_Read() is run on a socket that is set to non-blocking mode, and there is no data waiting to be read 
on the SSL enabled socket, the return value will be equal to -10 and the errno will be set to 
EWOULDBLOCK. 


Related Information 


e SSL Create()--Enable SSL Support for the Specified Socket Descriptor 


e SSL _Destroy(Q--End SSL Support for the Specified SSL Session 


e SSL _Handshake()--Initiate the SSL Handshake Protocol 


SSL_InitQ--Initialize the Current Job for SSL 


SSL_WriteQ--Write Data to an SSL-Enabled Socket Descriptor 
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SSL_Strerror()--Retrieve SSL Runtime Error 
Message 


Syntax 


#include <ssl.h> 

char* SSL_Strerror(int sslreturnvalue, 
SSLErrorMsg* serrmsgp) ; 

Service Program Name: QSOSSLSR 

Default Public Authority: *USE 

Threadsafe: Yes 


The SSZ_Strerror() function is used to retrieve an error message and associated text string which describes 
an SSL return value. 


Parameters 


int sslreturnvalue (Input) 
The Return Value received from a SSL API. 


SSLErrorMsg* serrmsgp (Input) 


The pointer to a SSLErrorMsg structure. If no SSLErrorMsg is provided, NULL must be entered. 
SSLErrorMssg is a typedef for a buffer of type struct SSLErrorMsgStr. In <ssl.h>, struct 
SSLErrorMssg is defined as the following: 


struct SSLErrorMsgStr { /* SSLErrorMsgStr */ 
char messageID[7]; /* Message identifier */ 
char messageFile[20]; /* Qualified message file name */ 


}; 
The fields within the SSLErrorMsg structure as pointed to by serrmsgp are defined as follows: 


char messageID[7] (output) 


The message identifier which defines the message associated with the input sslreturnvalue. 


char messageFile[20] (output) 


The fully qualified message file name where the message associated with the messagelD is 
stored. The first 10 characters specify the file name, and the second 10 characters specify 
the library. 


Authorities 


No authorization is required. 


Return Value 


The SSL_Strerror() API returns a pointer to the string. The null-terminated string is stored in the CCSID of 
the job. If the serrmsgp is provided, the SSLErrorMsg struct will be updated to reflect the message 
information corresponding to the string returned. 


Error Conditions 


If the sslreturnvalue is unrecognized, then an Unknown error message will be stored at the location 
pointed to by the return value. Other error conditions will be handled as described under Error Messages. 


Error Messages 


This API calls the Retrieve Message (QMHRTVM) API in order to perform its task. It inherits all error 
conditions from this function. If errors are encountered while using the Retrieve Message API, they will be 
reflected in the SSLErrorMsg fields (if provided) and any associated message replacement text will be 
stored at the location pointed to by the return value. 


Related Information 


e SSL PerrorQ--Print SSL Error Message 


e SSL Create()--Enable SSL Support for the Specified Socket Descriptor 
e SSL _DestroyQ--End SSL Support for the Specified SSL Session 

e SSL_Handshake()--Initiate the SSL Handshake Protocol 

e SSL_Init()--Initialize the Current Job for SSL 


e SSL Init ApplicationQ--Initialize the Current Job for SSL Processing Based on the Application 
Identifier 


e SSL _ Read()--Receive Data from an SSL-Enabled Socket Descriptor 
e SSL_WriteQ--Write Data to an SSL-Enabled Socket Descriptor 


Example 


The following example shows how SSL_Strerror() is used: 


#include <stdio.h> 
#include <sys/types.h> 
#include <sys/socket.h> 
#include <ssl.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 
#include <errno.h> 


/* bufferLen is 250 bytes */ 


#define bufferLen 250 


void main () 

{ 
int bufferLen, on = 1, re = 0, sd, sd2, addrlen = 0; 
char buffer[bufferLen]; 


SSLInit sslinit; 
SSLHandle* sslh; 


struct sockaddr_in addr; 


unsigned short int cipher[3] = { 
SSL_RSA_WITH_RC4_128_MD5, 
SSL_RSA_WITH_RC4_128_SHA, 
SSL_RSA_EXPORT_WITH_RC4_40_MD5 
}; 


[RK KK KK KK KK KK KK KK EK RK RK KK KK / 


/* memset sslinit structure to hex zeros and aed 
/* £111 an values for the sslinit structure ar 
[RK KKK KR RK KK KK KK RK KE RK KK KK KK / 
memset ((char *)&SSL_Init, 0x00, sizeof(sslinit)); 
sslinit.keyringFileName "/keyringfile.kyr"; 
sslinit.keyringPassword = NULL; 
sslinit.cipherSuiteList = &cipher[0]; 
sslinit.cipherSuiteListLen = 3; 


[RK KK KK RK KK KKK KK RK KK KK KK KK KK / 


/* initialize SSL security call SSL_Init */ 
[RK KKK KKK KK KK RK RK KK KK KK KKK / 
if ((rce = SSL_Init (ésslinit)) != 0) 


{ 
printf ("SSL_Init() failed with re = Sd $s \n" 
"and errno = %d %s \n",rc,SSL_Strerror(rc, NULL), 
errno, strerror(errno)); 


} 
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SSL_Write()--Write Data to an SSL-Enabled Socket 


Descriptor 


Syntax 


#include <ssl.h> 


int SSL _Write(SSLHandle *handle, 
void *buffer, 
int buffer_length) 


Service Program Name: QSOSSLSR 
Default Public Authority: *USE 


Threadsafe: Yes 


The SSL_Write() function is used by a program to write data to an SSL-enabled socket descriptor. 


Parameters 


SSLHandle* handle (input) 


The pointer to an SSLHandle for an SSL session. An SSLHandle is a typedef for a buffer of type struct 
SSLHandleStr. In <ssl.h>, struct SSLHandleStr is defined as the following: 


t SSLHandleStr { 
int fd; 


unsigned 
unsigned 
unsigned 
unsigned 
unsigned 
unsigned 


unsigned 
unsigned 
int 


int 


void *buffer (input) 


A pointer to the user-supplied buffer in which the data to be written is stored. 


timeout; 


int createFlags; 
protocol; 


, 


cipherKind[3]; 
int cipherSuite; 


int* cipherSuiteLi 
cipherSuiteLi 


/* SSLHandleStr 

/* Socket descriptor 

/* SSL_Create flags value 
/* SSL protocol version 
/* Timeout value in seconds 
/* Current 2.0 cipher suite*/ 
/* Current 3.0 cipher suite 


t; /* List of cipher suites 


peerCert; 
peerCertLen; 


peerCertValidateRc; 


tLen; /* Number of entries in 


the cipher suites list 
/* Peer certificate 
/* Peer certificate length 
/* Return code from 
validation of certficate 


(*exitPgm) (struct SSLHandleStr* sslh); 


/* Authentication exit 
program called when a 
certificate is received 
during SSL handshake 


int buffer_length (input) 
The length of the buffer. 


Authorities 


No authorization is required. 


Return Value 


SSL_Write() returns an integer. Possible values are: 


Value Description 
[n] Successful, where n is the number of bytes written. 
[SSL_ERROR_BAD_STATE] | SSL detected a bad state in the SSL session. 
[SSL_ERROR_CLOSED] The SSL session ended. 
[SSL_ERROR_IO] An error occurred in SSL processing; check the errno value. 
[SSL_ERROR_UNKNOWN]_ | An unknown or unexpected error occurred during SSL processing. 


Error Conditions 


When the SSL_Write() API fails with return code [SSL_ERROR_IO], errno can be set to to one of the following: 
[EBADF] Descriptor not valid. 


[EFAULT] Bad address. 


One of the following conditions occurred: 


e The system detected an address that was not valid while attempting to access the 
buffer parameter. 


e The system detected an address that was not valid while attempting to access the 
handle parameter or one of the address fields in the handle parameter. 


[EINTR] Interrupted function call. 


[EINVAL] Parameter not valid. 


This error code indicates one of the following: 


e The socket_descriptor type is not SOCK_STREAM or address family is not 
AF_INET 3 or AF_INET6%. 


e@ One of the parameters passed is not valid or is NULL. 


e The buffer_length parameter specifies a negative value. 


[EIO] Input/output error. 


[ENOBUFS] There is not enough buffer space for the requested operation. 


[ENOTCONN] Requested operation requires a connection. 


This error code indicates one of the following: 
e The socket_descriptor is not for a socket that is in a connected state. 


e The socket_descriptor has not had SSL support enabled. This usually means that an 
SSL_Create() has not been completed for this socket_descriptor. 


[ENOTSOCK] The specified descriptor does not reference a socket. 

[EPIPE] Broken pipe. 

[ETIMEDOUT] A remote host did not respond within the timeout period. 

[EUNATCH] The protocol required to support the specified address family is not available at this time. 
[EUNKNOWN] Unknown system state. 


[EWOULDBLOCK]_ Operation would have caused the thread to be suspended. 


Error Messages 


Message ID Error Message Text 
CPE3418 E Possible APAR condition or hardware failure. 
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


CPFA081 E Unable to set return value or error code. 


Usage Notes 


1. The SSL_Write() function is only valid on sockets that have an address family of AF_INET = or AF_INET6 
« and a socket type of SOCK_STREAM. If the descriptor pointed to by the handle structure parameter does 
not have the correct address family and socket type, [SSL_ERROR_IO] is returned and the errno value is set 
to EINVAL. 


2. There is no maximum length of the data that can be written. However, SSL will segment the data into 
multiple SSL record buffers if it will not fit in one SSL record buffer. The maximum SSL record size is 32 
KB minus the necessary SSL record headers. 


3. If the createFlags field in the SSLHandle specifies a value that does not include the SSL_LENCRYPT flag, 
then this function will simply call the sockets write() function. 


4. Unpredictable results will occur when attempting to mix calls to SSL_Write() and any of the sockets write 
functions (send(), write(), writev(), and so forth). It is strongly suggested that you do not mix the SSL_Write() 
API with any of the sockets write functions. 


Related Information 
e SSL _ Create(Q)--Enable SSL Support for the Specified Socket Descriptor 


e SSL_DestroyQ--End SSL Support for the Specified SSL Session 


e SSL_Handshake()--Initiate the SSL Handshake Protocol 


SSL_InitQ--Initialize the Current Job for SSL 


SSL_Read(Q)--Receive Data from an SSL-Enabled Socket Descriptor 


API introduced: V4R3 


Top | UNIX-Type APIs | APIs by category 


Header Files for UNIX-Type Functions 


Programs using the UNIX-type functions must include one or more header files that contain information 
needed by the functions, such as: 


e Macro definitions 
e Data type definitions 
e Structure definitions 
e Function prototypes 
The header files are provided in the QS YSINC library, which is optionally installable. Make sure 


QSYSINC is on your system before compiling programs that use these header files. For information on 
installing the QSYSINC library, see Data structures and the QSYSINC Library. 


The table below shows the file and member name in the QS YSINC library for each header file used by the 
UNIX-type APIs in this publication. 


Name of File in 
Name of Header File QSYSINC Name of Member 


[| arpa/ineth [| arpa/ineth [ ARPA [INET 


a 
a * 

tik | | so 
[  —sbseerrch CEC A~<“‘i‘~*Y:S*é‘éiBSEERRR 
[ss direnth [CM Rs—~<“i«i‘Cé«zYS)~OCéIRENT 
[ emoh [| H [ERRNO] | 
[_eph | SOS 

| evinttypes. h | | TNS 
ee ee ee 
[| %netinet/iemp6.h NETINE |  ICMP6& 
[| netinetinh NETINET [| WN 
| netinet/ip_icmp.h NETINET [|  IPICMP 


mo) oo) eo) eo) a) ee} ee} ey] 


| netinet/ip.h NETINET | IP 
| 2’netinet/ip6.h NETINET | IP6& 
| netinet/tcp.h NETINET TCP 


| netinet/udp.h NETINET UDP 

[netns/idph = | 0S NETNS) [CIDP 
[netns/ipxh = |S NETNS) [CPX 
[so netns/ns-h | NETNS) [CONST 
[so netns/sp-b |S NETNS) [SP 
[netrouteh = [)CNET)=—~<C;«é‘L”)~Ss*'<‘éROUTEECi:*s 
[—snettel/telLh «= sis[))sSNETTEL =o [)ti‘<‘STENRES—“( isis 


an 


[  oosh fC OS2 

[|  —sosddefh fC ASE S2DEF 
[ pwd fC PWD 

[0 gh fH QLG 

| —s qpOlfloph fs QPOLFLOP 
| Bqp0limih | | QPOLIRNLE 

| 2>qpOlror.h | | QPOLROR& 

|  qpOzolsm-h fC HH—C*ST ss QPOZOLSM 
| — qpOztrech fC QPOZTRE 
|  qpOztrmlh [| CSTs QPOZTRML 
| #qsoasync.h | | QSOASYNC% 
| qtnxaapi.h | QTNXAAPI 
[ qtnxadtph fC H——CSE ss QQTNXADTP 
|  qtomeapih sf] CM ™—C~@TSsC QQOMEEAP 


TRIG 


| qtossapi.h | H | QTOSSAPI 
| resolv.h | H | RESOLVE 


an 


| semaphore.h | | SEMAPHORE 


[signal | CMHC SIGNAL 
[|  spawnh Cf CM ™~“<~S SPAWN 
[ssh fA SSL 

| sysferrnoh = fC H™:~iT SC ERRNOU 
[| sysfioctLh SYS [|  IOCTL 
| ——ssys/ipeh SYS [ woe 


| sys/layout.h | H | LAYOUT 
| sys/limits.h | H | LIMITS 


| —ssys/msg-ho SYS MSG 

[| sys/param.h SYS [ PARAM 
| #*sys/resource.h SYS | RESOURCE® 

| —ssys/sem-h SYS SEM 

| sys/setimp.h SYS | ‘SETIMP 
| sys/shm.h SYS SHM 

[| sys/signalh SYS [ SIGNAL 
[| _sys/socketh SYS [SOCKET 
[| —sys/stath SYS [ STAT” 


| sys/statvfs.h SYS | STATVFS 


| —ssysfimeh SYS [| TIME 
[| sys/types.b SYS [TYPES si 
| —ssys/uio.h SYS UIO 

[ sys SYS [ UN 
| —ssys/waith SYS | WAIT 
| Sulimit.h H | ULIMIT*& 

[| sounistdh fC HSE UNISTD 
[  soutimeh fC UTIME 


You can display a header file in QS YSINC by using one of the following methods: 


e Using your editor. For example, to display the unistd.h header file using the Source Entry Utility 
editor, enter the following command: 


STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION(5) 


e Using the Display Physical File Member command. For example, to display the sys/stat.h header 
file, enter the following command: 


DSPPFM FILE(QSYSINC/SYS) MBR(STAT) 


You can print a header file in QSYSINC by using one of the following methods: 


e Using your editor. For example, to print the unistd.h header file using the Source Entry Utility 
editor, enter the following command: 


STRSEU SRCFILE(QSYSINC/H) SRCMBR(UNISTD) OPTION (6) 
e Using the Copy File command. For example, to print the sys/stat.h header file, enter the following 


command: 


CPYF FROMFILE(QSYSINC/SYS) TOFILE(*PRINT) FROMMBR (STAT) 


Symbolic links to these header files are also provided in directory /QIBM/include. 
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Errno Values for UNIX-Type Functions 


Programs using the UNIX-type functions may receive error information as errno values. The possible 
values returned are listed here in ascending errno value sequence. 


[Name [Value [Test 

~——— a ee domain error occurred in a math 
function. 

[ERANGE = GE [300200 A [Arangeerror occurred. = error [Arangeerror occurred. = 

—| C _— Data was truncated on an input, output, or 
update operation. 

EN [ENOTOPEN [3004 [Fileisnotopen. is not [Fileisnotopen. 


—— OTREAD — [File i is not opened for read operations. 
EIO [3006 [Input/output error. 


EN [ENODEV [3007 N [Nosuchdevice. [Nosuchdevice. device. 

ae —_ Cannot get single character for files 
opened for record I/O. 

EN [ENOTWRITE [30090 [File is not opened for write operations. is not [File is not opened for write operations. for write operations. 


a —— [The stdin stream cannot be opened. 
[ESTDOUT [3011 [The stdout stream cannot be opened. 


[ESTDERR [30120 [The stderr stream cannot be opened. stderr stream cannot be [The stderr stream cannot be opened. 

_—| a The positioning parameter in fseek is not 
correct. 

[EBADNAME AME [30140 [The object name specified is not correct. — [The object name specified is not correct. — name specified is not correct. 


a ——! The type variable specified on the open 
function is not correct. 


[EBADPOS 3017s [The position specifier is not correct. position [The position specifier is not correct. is not correct. 


17 
EN a — There is no record at the specified 
position. 
ENUMMBRS 3019 Attempted to use ftell on multiple 
members. 
ENUMRECS 3020 The current record position is too long for 
ftell. 
EINVAL 3021 The value specified for the argument is not 
correct. 
EBADFUNC 3022 Function parameter in the signal function 
is not set. 
[302500 


EN [ENOENT T No [No such path or directory, = [No such path or directory, = or directory. 


FoR? ——— ht’ —— ae 
[EPERM  =——<CS~s«LB27_~——SSC«*d Phe Oplerationn is not permitted. = 
[EBADDATA  ——s[3028——Ss[Meessage dataisnotvalid. = 
[EBUSY ==—=«S(38029—s Resource busy, 
[EBADOPT —s*(3040 = Option specified is not valid. 
[ENOTUPD ~—s*([3041 =~‘ File is not opened for update operations. 
[ENOTDLT ~—*[3042. [File is not opened for delete operations. 


EPAD 3043 The number of characters written is 
shorter than the expected record length. 

EBADKEYLN 3044 A length that was not valid was specified 
for the key. 

EPUTANDGET 3080 A read operation should not immediately 
follow a write operation. 

EGETANDPUT 3081 A write operation should not immediately 
follow a read operation. 

[EIOERROR [3101 [A nonrecoverable I/O error occurred. 

[EIORECERR [3 102 [A recoverable I/O error occurred. 

[EACCES [3401 [Permission denied. 


[EN OTDIR [3403 [N ot a directory. 
[ENOSPC [3404 [No space is available. 


[EXDEV [3405 Improper link, [Improperlink, 


[34050 
aa_— 3406 Operation would have caused the process 
to be suspended. 
EWOULDBLOCK 3406 Operation would have caused the process 
to be suspended. 
[3407 


[EINTR [3407 SS s‘[Interrupted function call. [Interrupted function call. call. 


ee— 3408 The address used for an argument was not 
correct. 


[ETIME [3409 [3409 [Operation timedout. [Operation timedout. out. 
—_——— [3415 0 No [No such device oraddress. device [No such device oraddress. address. 
SEs i Pa 
failure 
[ERECURSE [3419 [Recursive attempt rejected. = attempt [Recursive attempt rejected. = 
 ORNESE Si —— see 
[EADDRNOTAVAIL [342200 [Address is notavailable. = [Address is notavailable. = not available. 
ESINOSUORT > pean type of socket is not supported in this 
protocol family. 
[EALREADY [342300 [3423 [Operation is already in progress. = is already in progress. 
REE ABORTED [34240000 [Connection ended abnormally. ended [Connection ended abnormally. 
25 


ECONNRTUSED — aS rma ba tn te 
connect operation 
i ae ce 
reset by that socket 
[EDESTADDRREQ. [3427 00 [3427 | Operation requires destination address. requires [Operation requires destination address. address. 
[EHOSTDOWN [3428s {Ar remote host is notavailable. 
[EHOSTUNREACH [3429 ‘A route to the remote host is not available. 
[EINPROGRESS —[3430. Ss |Operationin progress. = 
[EISCONN «(3431s {A connection has already been established. 
[EMSGSIZE «(3432s [Message size isoutofrange. 
[ENETDOWN  ——s[3433.—s*[ The network currently is not available. 


ENETRESET 3434 A socket is connected to a host that is no 
longer available. 


[ENETUN REACH [3435 [Cannot reach the destination network. 

ENOBUFS 3436 There is not enough buffer space for the 
requested operation. 

ENOPROTOOPT 3437 The protocol does not support the 

specified option. 

ENOTCONN 3438 Requested operation requires a 
connection. 

ENOTSOCK 3439 The specified descriptor does not 
reference a socket. 

[EN OTSUP [3440 [Operation is not supported. 

[EOPN OTSUPP [3440 [Operation is not supported. 


EPFNOSUPPORT 3441 The socket protocol family is not 
supported. 

EPROTONOSUPPORT |3442 No protocol of the specified type and 
domain exists. 

EPROTOTYPE 3443 The socket type or protocols are not 
compatible. 

ERCVDERR 3444 An error indication was sent by the peer 
program. 


[ESHUTDOWN [3445 [Cannot send data after a shutdown. 
[ESOCKTN OSUPPORT [3446 [The specified socket type is not supported. 


ETIMEDOUT 3447 A remote host did not respond within the 
timeout period. 

EUNATCH 3448 The protocol required to support the 
specified address family is not available at 
this time. 


[EBADF = =—S—=«&;3'45——SsDescriptorisnot valid, 
[EMFILE  =—S*[3452,—S——Ss {Too many open files for this process. 
[ENFILE =——=S&3453. Ss [Too many open files inthe system. 
EPIPE == ~—«*(3455, ss (Brokenpipe. 
[ECANCEL =——s«[3456.———s|Operationcancelled. = 
[EEXIST =———s«*(3'KST_—— sie exists, 
[EDEADLK =——s*[3459_ Resource deadlock avoided. 
[ENOMEM ——s«[3460—Ss« Storage allocation request failed. = 
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a 34 The synchronization object no longer 
exists because the owner is no longer 
running. 

EDESTROYED 3463 The synchronization object was destroyed, 
or the object no longer exists. 

[ETERM [3464 00—CO [3464 Operation was terminated. = was [Operation was terminated. = 


aes —— OENT1 [3 465 [N o such file or directory. 


ENOEQFLOG 3466 Object is already linked to a dead 
ones sag 


[EEMPTYDIR [3 467 [Directoryisempty. = is empty. 


EMLINK 3468 Maximum link count for a file was 
exceeded. 


ESPIPE  =—~SC~«&346—— “Seek request is not supported for object. 
[ENOSYS —————=«*3470.—S—SSs|Function not implemented. = 
[EISDIR ——i(ass—t*é«*BATALC Specified targetisadirectory, = 
[EROFS =———~—é«i;3B220-—— Read-only file system. 
[EUNKNOWN  —s[3474.— ss [Unknown system state. = 
[EITERBAD  =——s«(34750—— iterator isnotvalid. = 
[EITERSTE  =—sS*(3476 ~—S—SCs=|Iterator is in wrong state for operation. 
[EHRICLSBAD —s [3477 Ss HIRI classisnotvalid. 
[EHRICLBAD ~—s([3478 = {IRI subclassisnot valid. = 
[EHRITYPBAD —[3479 Ss {HRI typeisnotvalid, = 
[ENOTAPPL —=—s*[3480.—~——Ss [Datta requested is not applicable. = 
[EHRIREQTYP  =—[3481_ = {ARI request type isnot valid. 
[EHRINAMEBAD —_ [3482s {HRT resource name isnot valid. 
[EDAMAGE —s([3484.————s [A damaged object was encountered. 
[ELOOP  ———~™—=é«S;3485— SA cop exists in the symbolic links. 
[ENAMETOOLONG [3486 = {Apathnameistoolong, 
[ENOLCK = =——s«*(3487,——s No locksare available. = 
[ENOTEMPTY —*[3488 ~=——Ss[Directory isnotempty. = 
[ENOSYSRSC [3489s System resources are not available. = 
[ECONVERT =— [3490s |Conversionerror, 


[E2BIG [3491 [3491 Ss [Argumentlististoolong, [Argument lististoolong, = is too long. 
—=———— 3492 Conversion stopped due to input character 
that does not belong to the input codeset. 


[ETYPE  ——™ [3493 [3493 |Objecttypemismatche type [Object type mismatch, 
—— 3494 Attempted to reference a directory that 
was not found or was destroyed. 
EBADOBJ 3495 Attempted to reference an object that was 
not found, was destroyed, or was 
damaged. 
EIDXINVAL 3496 Data space index used as a directory is not 
valid. 
[ESOFTDAMAGE [3497 [3497 [Objecthas softdamage. [Objecthas softdamage. soft damage. 


Soe | OTENROLL 3498 User is not enrolled in system distribution 
ies sae———— 


[EOFFLINE = 3499 [3499 |Objectissuspended. is suspended. 


[34990 
oe —— [3 500 [Object i is a read-only object. 


EEAHDDSI 3501 Hard damage on extended attribute data 
space index. 

EEASDDSI 3502 Soft damage on extended attribute data 
space index. 

EEAHDDS 3503 Hard damage on extended attribute data 
space. 

EEASDDS 3504 Soft damage on extended attribute data 

| | ee 


[EEADUPRC [3505 [Duplicate extended attribute record. 


ELOCKED 3506 Area being read from or written to is 
locked. 


[EFBIG [3507 [3507 ss |Objecttoolarge. [Objecttoolarge, large. 
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a—_—— 3 The semaphore, shared memory, or 
message queue identifier is removed from 
the system. 

OMSG e The queue does not contain a message of 


the desired type and (msgflg logically 
ANDed with IPC_NOWAIT). 


[EFILECVT = [351k [File ID conversion of a directory failed. ID conversion of a [File ID conversion of a directory failed. failed. 

a——— _— A file ID could not be assigned when 
linking an object to a directory. 

[ESTALE [3513 [File handle was rejected by server. handle was [File handle was rejected by server. by server. 


es} — oes 
[ENOTSIGINIT ——[3516 [Process is not enabled for signals. 

[ECHILD  =———~—=«~S(;B'SS'T.— Ss Nochild process. 
[EBADH = =—sS«(3520.——sHandleisnotvalid, = 


iN YREFS 3523 The operation would have exceeded the 


maximum number of references allowed 
for a descriptor. 


[ENOTSAFE =——s [3524s |Functionisnotallowed. = 
ESC aW—— sk —— pice ee ——— 
[EIRNDAMAGE ~—[3526 Ss |Jourmalisdamaged. 
[EJRNINACTIVE ~— [3527s |Jourmalisimactive, = 
[EIRNRCVSPC [3528 = s‘|Journal space or system storage error. 
[EIRNRMT = ——s*(3529, Ss Journalisremote. 
[ENEWJRNRCV [3530s [New journal receiver isneeded. 
[ENEWJRN  ———s«(3531.=——Ss New journalisneeded. = 
[EJOURNALED [3532s Objectalready journaled. = 
[EIRNENTTOOLONG 3533 [Entry istoolargetosend. 
[EDATALINK —s [3534s [Object is adatalink object. 
[ENOTAVAIL ~—s 3535. IASPisnotavailable. = 


[ENOTTY = OTTY [35360 [I/O control operation is not appropriate. control [I/O control operation is not appropriate. is not appropriate. 

sues 3540 Attempt to write or truncate file past its 
=o ie file size limit. 

[ETXTBSY [35430 [Textfilebusy. file [Textfilebusy. 

SENG OTSET ~— [ASP group not set forthread. [ASP group not set forthread. not set for thread. 


—— a A system call was interrupted and may be 
restarted. 
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